Merge pull request 'docs(android): update NDK reference to 30.0.14904198' (#108 ) from docs/android-ndk-version into master

docs(android): update NDK reference to 30.0.14904198
The setup doc pinned NDK 26.3.11579264, but newer NDKs build fine (verified locally on 30.0.14904198 / build-tools 37.0.0: cross-compile, android-target clippy, and a full signed arm64-v8a APK). Note that the exact versions are not load-bearing and build_android_apk.sh auto-discovers the newest installed NDK/build-tools. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 17:37:03 +00:00 · 2026-06-25 10:36:48 -07:00 · 2026-06-25 17:20:48 +00:00 · 2026-06-25 17:13:51 +00:00 · 2026-06-25 10:13:39 -07:00 · 2026-06-25 17:11:26 +00:00
134 changed files with 8390 additions and 3856 deletions
@@ -6,6 +6,8 @@ on:
    branches: [master]
    paths:
      - 'solitaire_server/**'
+      - 'solitaire_wasm/**'
+      - 'solitaire_web/**'
      - 'solitaire_sync/**'
      - 'solitaire_core/**'
      - 'solitaire_engine/**'
@@ -34,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:
@@ -57,8 +66,6 @@ jobs:
            ${{ env.IMAGE }}:latest
          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max
-          secrets: |
-            cargo_token=${{ secrets.CI_TOKEN }}

      - name: Install kustomize
        run: |
@@ -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
@@ -6,6 +6,287 @@ project follows [Semantic Versioning](https://semver.org/).

 ## [Unreleased]

+### Added
+
+- **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
+
+- **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
+
+- **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

@@ -2083,11 +2083,13 @@ dependencies = [

 [[package]]
 name = "card_game"
-version = "0.4.0"
+version = "0.4.1"
 source = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
-checksum = "d206df6d87340019a0f5b621976cf98bc75c659a7f93ef348aaab2a9336098a9"
+checksum = "983728ead19f51d96931725706e62293bd133ac3d836097dd7d745e929f7811b"
 dependencies = [
 "arrayvec 0.7.6 (sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/)",
+ "serde",
+ "serde_derive",
 ]

 [[package]]
@@ -4305,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]]
@@ -4599,12 +4601,14 @@ dependencies = [

 [[package]]
 name = "klondike"
-version = "0.3.0"
+version = "0.4.0"
 source = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
-checksum = "347d55e6cf7c90b3d038262071eb2fdb0b75a713fe66c452a3400ff08fb716bc"
+checksum = "d5c82b0c3abd7da07b4a1c4221a809e6e2ffd475ae0e67180fbfef35a9cfe769"
 dependencies = [
 "card_game",
 "rand 0.10.1",
+ "serde",
+ "serde_derive",
 ]

 [[package]]
@@ -6059,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"
@@ -6103,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"
@@ -6301,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"
@@ -6790,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"
@@ -7256,6 +7306,7 @@ name = "solitaire_app"
 version = "0.1.0"
 dependencies = [
 "bevy",
+ "jni 0.21.1",
 "keyring",
 "solitaire_data",
 "solitaire_engine",
@@ -7279,6 +7330,7 @@ version = "0.1.0"
 dependencies = [
 "card_game",
 "klondike",
+ "proptest",
 "serde",
 "thiserror 2.0.18",
 ]
@@ -7289,7 +7341,7 @@ version = "0.1.0"
 dependencies = [
 "async-trait",
 "axum",
- "bevy",
+ "card_game",
 "chrono",
 "dirs",
 "jni 0.21.1",
@@ -7322,7 +7374,6 @@ dependencies = [
 "image",
 "jni 0.21.1",
 "kira",
- "klondike",
 "reqwest",
 "resvg",
 "ron",
@@ -7382,7 +7433,6 @@ dependencies = [
 "chrono",
 "console_error_panic_hook",
 "getrandom 0.3.4",
- "klondike",
 "serde",
 "serde-wasm-bindgen",
 "serde_json",
@@ -8846,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"
@@ -9052,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"
@@ -18,6 +18,22 @@ 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"
@@ -38,8 +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.3.0", registry = "Quaternions" }
-card_game        = { version = "0.4.0", registry = "Quaternions" }
+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,38 @@
 # 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-09 — AVD Android launch smoke passed; 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 validation runbooks, card-label test coverage, and Android AVD smoke notes.
+- **Latest tag:** `v0.39.0`
+- **Working tree:** clean. Local `scripts/` helpers are excluded through `.git/info/exclude` and intentionally not committed.
+- **Latest verification in this follow-up:** `cargo test -p solitaire_core`; `cargo test -p solitaire_data matomo_client`; `cargo test -p solitaire_engine analytics_plugin`; `cargo test -p solitaire_engine settings_plugin`; `cargo test -p solitaire_engine card_plugin`; `cargo apk build -p solitaire_app --target x86_64-linux-android --lib`; AVD `Pixel_7` install/launch/input smoke.
+- **Full previous gate:** Claude reported recent card_game work pushed to origin and `cargo test` / `clippy` gates passing before the changelog follow-up.
+
+---
+
+## 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 +103,27 @@ Three bugs fixed:

 ## Open punch list

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

 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"
+and run the checklist in `docs/ANDROID.md`. 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.

-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

-`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.
+`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 +145,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`.
@@ -22,6 +22,22 @@ 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
@@ -65,7 +81,11 @@ wasm-bindgen \
 # 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..."
-    wasm-opt -Oz \
+    # 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
@@ -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.
@@ -2,7 +2,10 @@

 **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:** Most gaps are closed in Ferrous Solitaire's own `solitaire_core` crate via a wrapper/adapter layer. Gaps 1, 3, and 4 have been addressed upstream. Integration is ready to begin.
+**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`.

 ---

@@ -42,10 +45,12 @@

 ---

-## What Ferrous Solitaire's `solitaire_core` Needs (Gaps)
+## What Ferrous Solitaire's `solitaire_core` Still Owns

 ### 1. Scoring — remaining adapter responsibilities
-Ferrous uses **Windows XP Standard** scoring. The exact table already implemented in `solitaire_core/src/scoring.rs`:
+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 |
 |---|---|---|
@@ -61,11 +66,13 @@ Ferrous uses **Windows XP Standard** scoring. The exact table already implemente

 Reference: <https://www.solitaireparadise.com/games_list/klondike_solitaire_scoring.html>

-**Undo penalty:** `SessionState::score()` = `KlondikeStats.score(&scoring) + undos × undo_penalty`. The −15 undo penalty is built into `SessionConfig` (default). Once `GameState` fully delegates to `Session`, our `KlondikeAdapter::score_for_undo()` helper becomes redundant.
+**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:** Configure `ScoringConfig` with the WXP deltas for the five events upstream handles (including undo via `SessionConfig`). Implement recycle-with-free-allowance, score floor, and time bonus in the adapter.
+**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:
@@ -78,7 +85,9 @@ Ferrous has three modes that alter scoring and undo behaviour:

 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:** Add `GameMode` to `solitaire_core::GameState`; intercept undo calls and scoring deltas in the adapter before delegating to `KlondikeState`.
+**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:
@@ -87,23 +96,33 @@ Zen is intended for relaxed play where the score does not matter. Challenge is a

 `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).

-Our 767-line `solitaire_core::solver` reimplements the full game rules to run the DFS; `session.solve()` replaces it entirely. The solver will be removed once the `Session<Klondike>` is wired into `GameState`.
+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:** Replace `solitaire_core::solver` with `session.solve()`. Map `Ok(Some(_))` → Winnable, `Ok(None)` → Unwinnable, `Err(_)` → Inconclusive.
+**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.

-**Important:** The upstream default is `MoveFromFoundationConfig::Allowed`. Ferrous Solitaire uses the standard rule (foundation cards cannot be moved back) as the default, with the house rule as an opt-in. Our adapter explicitly sets `Disallowed` in the default `KlondikeConfig` and switches to `Allowed` only when the user toggles the house-rule option.
+**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:** Construct `KlondikeConfig { move_from_foundation: MoveFromFoundationConfig::Disallowed, .. }` by default; mirror the user's settings toggle to `Allowed`. No custom intercept needed — `klondike` enforces the rule automatically.
+**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. `KlondikeState` derives `Clone` + `Eq` + `Hash` but not `Serialize` / `Deserialize`. No upstream changes are needed — this is handled externally.
+`solitaire_core::GameState` serialises the full mid-game state to JSON via `serde` so the engine can save on exit and restore on launch.

-**Session history:** `StateSnapshot<G>` stores the pre-move game state and instruction. On load, the session is reconstructed from the serialised snapshot history — no full replay from seed needed.
+**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"]`.

-**In our wrapper:** Serialise the `solitaire_core` wrapper struct using newtypes. Define `SavedInstruction` (a `Serialize + Deserialize` mirror of `KlondikeInstruction`) and `SavedStateSnapshot`. Reconstruct `SessionState` from the deserialised history. Schema version field lives on our wrapper.
+**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.):
@@ -129,7 +148,9 @@ Ferrous tracks `PileType::Waste` as a distinct pile. `klondike` folds waste into
 ### 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:** Use `Session`'s built-in snapshot history. Our `GameState.undo_stack: VecDeque<StateSnapshot>` will be removed once `GameState` is fully migrated to delegate to `Session`.
+**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.

 ---

@@ -138,12 +159,35 @@ Ferrous tracks `PileType::Waste` as a distinct pile. `klondike` folds waste into
 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 `PileType::Waste`; expose the same `HashMap<PileType, Pile>` the engine already reads. Wire `Session<Klondike>` into `KlondikeAdapter` (gap 7).
-3. ✅ **Configure `KlondikeConfig`** — set `move_from_foundation: MoveFromFoundationConfig::Disallowed` by default; wire the user's house-rule toggle to `Allowed` (gap 4, upstream).
+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 our `SolverConfig`; map `Ok(Some)` → Winnable, `Ok(None)` → Unwinnable, `Err` → Inconclusive (gap 3, upstream).
-7. **Implement `serde`** — define `SavedInstruction` + `SavedStateSnapshot` newtypes; serialise session history; migrate save-file schema (gap 5).
+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`

 ---

@@ -163,5 +207,5 @@ Steps in dependency order. Upstream issues #10, #11, and the solver are all merg
 - Upstream scoring + config PRs: #12 (closes #11), #13 (closes #10)
 - Upstream solver PR: #14
 - `solitaire_core` source: `solitaire_core/src/`
- Scoring spec: `solitaire_core/src/scoring.rs`
+- 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" \
@@ -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"
@@ -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()
@@ -355,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,8 +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 }
 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,503 +1,85 @@
 //! Adapter bridging `solitaire_core` types to the upstream `klondike` crate.
 //!
-//! # Current scope (integration steps 1–4)
+//! [`KlondikeAdapter`] is a pure helper namespace for:
+//! - building [`KlondikeConfig`] from Ferrous settings
+//! - translating between local and upstream types
 //!
-//! [`KlondikeAdapter`] owns the authoritative [`KlondikeConfig`] and exposes
-//! scoring helpers backed by [`ScoringConfig::DEFAULT`] (Windows XP Standard
-//! values).  [`GameState`] delegates scoring here so that klondike remains the
-//! single source of truth for scoring constants.
+//! Ferrous-specific scoring policy (the win-time bonus) lives in
+//! [`crate::scoring`], not here.
 //!
-//! # Not yet implemented
-//!
-//! - Live [`klondike::Klondike`] shadow state (requires pile-mapping, step 2).
-//! - Move validation via klondike's rule engine (step 2).
-//! - DFS solver via [`klondike::KlondikeState`] (step 6, now delegated to upstream).
+//! 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 card_game::{Card as KlCard, Rank as KlRank, Suit as KlSuit};
 use klondike::{
-    DrawStockConfig, DstFoundation, DstTableau, Foundation, KlondikeConfig, KlondikeInstruction,
-    KlondikePile, KlondikePileStack, MoveFromFoundationConfig, ScoringConfig, SkipCards, Tableau,
-    TableauStack,
+    DrawStockConfig, Foundation, KlondikeConfig, MoveFromFoundationConfig, ScoringConfig,
+    SkipCards, Tableau,
 };
-use serde::{Deserialize, Serialize};

-use crate::game_state::{DrawMode, GameMode};
-
-/// Bridges `solitaire_core` game config and scoring to the upstream `klondike` crate.
+/// Bridges `solitaire_core` game config to the upstream `klondike` crate.
 ///
-/// Holds a [`KlondikeConfig`] reflecting the current game settings and exposes
-/// scoring helpers that read from [`ScoringConfig::DEFAULT`] (WXP values).
-/// [`GameState`] uses this instead of calling `scoring.rs` functions directly.
-#[derive(Clone, Debug)]
-pub struct KlondikeAdapter {
-    config: KlondikeConfig,
-}
-
-impl PartialEq for KlondikeAdapter {
-    fn eq(&self, other: &Self) -> bool {
-        self.config.draw_stock == other.config.draw_stock
-            && self.config.move_from_foundation == other.config.move_from_foundation
-    }
-}
-impl Eq for KlondikeAdapter {}
-
-impl Default for KlondikeAdapter {
-    /// Returns an adapter with Draw-1 and `take_from_foundation = true`,
-    /// matching `GameState`'s own defaults.  Used by `#[serde(skip)]`
-    /// field initialisation on deserialisation.
-    fn default() -> Self {
-        Self::new(DrawMode::DrawOne, true)
-    }
-}
+/// 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 {
-    /// Create an adapter from the game's draw mode and foundation house-rule setting.
-    ///
-    /// `take_from_foundation = true` maps to [`MoveFromFoundationConfig::Allowed`];
-    /// `false` maps to [`MoveFromFoundationConfig::Disallowed`].
-    pub fn new(draw_mode: DrawMode, take_from_foundation: bool) -> Self {
-        let config = KlondikeConfig {
-            draw_stock: match draw_mode {
-                DrawMode::DrawOne => DrawStockConfig::DrawOne,
-                DrawMode::DrawThree => DrawStockConfig::DrawThree,
-            },
+    /// 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,
-        };
-        Self { config }
-    }
-
-    /// Returns a reference to the underlying [`KlondikeConfig`].
-    ///
-    /// Used by the solver and pile-mapping code added in later integration steps.
-    pub fn klondike_config(&self) -> &KlondikeConfig {
-        &self.config
-    }
-
-    /// Update the foundation house-rule flag, keeping [`KlondikeConfig`] in sync.
-    pub fn set_take_from_foundation(&mut self, allowed: bool) {
-        self.config.move_from_foundation = if allowed {
-            MoveFromFoundationConfig::Allowed
-        } else {
-            MoveFromFoundationConfig::Disallowed
-        };
-    }
-
-    // ── Scoring helpers ───────────────────────────────────────────────────
-
-    /// Score delta for a card move.
-    ///
-    /// Reads from [`ScoringConfig`] (WXP Standard values):
-    /// - Any pile → Foundation: +10
-    /// - Waste → Tableau: +5
-    /// - Foundation → Tableau: −15
-    /// - All other moves: 0
-    pub fn score_for_move(&self, from: &KlondikePile, to: &KlondikePile) -> i32 {
-        let sc = &self.config.scoring;
-        match (from, to) {
-            (_, KlondikePile::Foundation(_)) => sc.move_to_foundation,
-            (KlondikePile::Stock, KlondikePile::Tableau(_)) => sc.move_to_tableau,
-            (KlondikePile::Foundation(_), KlondikePile::Tableau(_)) => sc.move_from_foundation,
-            _ => 0,
-        }
-    }
-
-    /// Score delta for exposing a face-down tableau card: +5.
-    pub fn score_for_flip(&self) -> i32 {
-        self.config.scoring.flip_up_bonus
-    }
-
-    /// Score delta for undo: −15.
-    ///
-    /// [`card_game::Session`] handles this via `SessionConfig::undo_penalty`
-    /// (default −15). We mirror the constant here so `GameState` can apply it
-    /// in its snapshot-based undo path without owning a `Session`.
-    pub const fn score_for_undo() -> i32 {
-        -15
-    }
-
-    /// Score delta for recycling waste → stock.
-    ///
-    /// [`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:
-    ///
-    /// | Mode | Free recycles | Penalty per extra recycle |
-    /// |---|---|---|
-    /// | Draw-1 | 1 | −100 |
-    /// | Draw-3 | 3 | −20 |
-    ///
-    /// `recycle_count` must be the new total **after** this recycle.
-    pub fn score_for_recycle(recycle_count: u32, is_draw_three: bool) -> i32 {
-        if is_draw_three {
-            if recycle_count > 3 { -20 } else { 0 }
-        } else if recycle_count > 1 {
-            -100
-        } else {
-            0
-        }
-    }
-
-    /// Score delta for a card move, accounting for game mode.
-    ///
-    /// Returns 0 in [`GameMode::Zen`] (all scoring suppressed).
-    pub fn score_for_move_with_mode(
-        &self,
-        from: &KlondikePile,
-        to: &KlondikePile,
-        mode: GameMode,
-    ) -> i32 {
-        if mode == GameMode::Zen { 0 } else { self.score_for_move(from, to) }
-    }
-
-    /// Score delta for exposing a face-down card, accounting for game mode.
-    ///
-    /// Returns 0 in [`GameMode::Zen`].
-    pub fn score_for_flip_with_mode(&self, mode: GameMode) -> i32 {
-        if mode == GameMode::Zen { 0 } else { self.score_for_flip() }
-    }
-
-    /// Compute the new score after an undo, accounting for game mode.
-    ///
-    /// In [`GameMode::Zen`] the score is always 0. Otherwise applies the
-    /// −15 undo penalty and clamps to 0 via [`Self::score_for_undo`].
-    pub fn apply_undo_score(snapshot_score: i32, mode: GameMode) -> i32 {
-        if mode == GameMode::Zen {
-            0
-        } else {
-            (snapshot_score + Self::score_for_undo()).max(0)
-        }
-    }
-
-    /// Score delta for recycling, accounting for game mode.
-    ///
-    /// Returns 0 in [`GameMode::Zen`].
-    pub fn score_for_recycle_with_mode(
-        recycle_count: u32,
-        is_draw_three: bool,
-        mode: GameMode,
-    ) -> i32 {
-        if mode == GameMode::Zen {
-            0
-        } else {
-            Self::score_for_recycle(recycle_count, is_draw_three)
        }
    }
 }

-// ── Type-conversion utilities ─────────────────────────────────────────────
-
-/// Convert [`card_game::Suit`] back to our [`crate::card::Suit`].
-pub(crate) fn suit_from_kl(suit: KlSuit) -> crate::card::Suit {
-    match suit {
-        KlSuit::Clubs    => crate::card::Suit::Clubs,
-        KlSuit::Diamonds => crate::card::Suit::Diamonds,
-        KlSuit::Hearts   => crate::card::Suit::Hearts,
-        KlSuit::Spades   => crate::card::Suit::Spades,
+/// 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 [`card_game::Rank`] back to our [`crate::card::Rank`].
-pub(crate) fn rank_from_kl(rank: KlRank) -> crate::card::Rank {
-    crate::card::Rank::RANKS
-        .into_iter()
-        .find(|r| r.value() == rank as u8)
-        .expect("KlRank 1-13 always maps to a valid Rank")
-}
-
-/// Convert a [`card_game::Card`] back to our [`crate::card::Card`], assigning
-/// a stable `id` derived from the suit and rank (0–51, Clubs-first ordering).
-///
-/// The id is consistent for the same logical card across all reconstructions.
-pub fn card_from_kl(card: &KlCard) -> crate::card::Card {
-    let suit = suit_from_kl(card.suit());
-    let rank = rank_from_kl(card.rank());
-    let suit_index = crate::card::Suit::SUITS
-        .iter()
-        .position(|s| *s == suit)
-        .expect("suit always in SUITS") as u32;
-    let id = suit_index * 13 + (rank.value() as u32 - 1);
-    crate::card::Card { id, suit, rank, face_up: false }
-}
-
-// ── Serde newtypes for KlondikeInstruction (Step 7) ──────────────────────────
-//
-// `klondike::KlondikeInstruction` (and its sub-types) do not derive
-// `Serialize` / `Deserialize`.  These mirror types carry `#[serde]` so that
-// the session instruction history can be persisted and reconstructed without
-// upstream changes.
-//
-// Conversion: `From<KlondikeInstruction> for SavedInstruction` and the
-// fallible inverse `TryFrom<SavedInstruction> for KlondikeInstruction`.
-// Invalid numeric values (out-of-range u8 for tableau/foundation/skip) yield
-// `InvalidSavedInstruction`.
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::Tableau`] (0 = Tableau1 … 6 = Tableau7).
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SavedTableau(pub u8);
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::Foundation`] (0 = Foundation1 … 3 = Foundation4).
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SavedFoundation(pub u8);
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::SkipCards`] (0 = Skip0 … 12 = Skip12).
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SavedSkipCards(pub u8);
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::KlondikePile`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub enum SavedKlondikePile {
-    Tableau(SavedTableau),
-    Stock,
-    Foundation(SavedFoundation),
-}
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::TableauStack`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SavedTableauStack {
-    pub tableau: SavedTableau,
-    pub skip_cards: SavedSkipCards,
-}
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::KlondikePileStack`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub enum SavedKlondikePileStack {
-    Tableau(SavedTableauStack),
-    Stock,
-    Foundation(SavedFoundation),
-}
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::DstFoundation`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SavedDstFoundation {
-    pub src: SavedKlondikePile,
-    pub foundation: SavedFoundation,
-}
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::DstTableau`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SavedDstTableau {
-    pub src: SavedKlondikePileStack,
-    pub tableau: SavedTableau,
-}
-
-/// A `Serialize` + `Deserialize` mirror of [`klondike::KlondikeInstruction`].
-///
-/// Convert to/from the upstream type with:
-/// ```ignore
-/// let saved = SavedInstruction::from(instruction);
-/// let instruction = KlondikeInstruction::try_from(saved)?;
-/// ```
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub enum SavedInstruction {
-    DstFoundation(SavedDstFoundation),
-    DstTableau(SavedDstTableau),
-    RotateStock,
-}
-
-/// Error returned when a [`SavedInstruction`] contains an out-of-range numeric value
-/// and cannot be converted back to a [`klondike::KlondikeInstruction`].
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
-pub enum InvalidSavedInstruction {
-    #[error("invalid tableau index {0} (expected 0–6)")]
-    Tableau(u8),
-    #[error("invalid foundation index {0} (expected 0–3)")]
-    Foundation(u8),
-    #[error("invalid skip_cards value {0} (expected 0–12)")]
-    SkipCards(u8),
-}
-
-// ── From impls: KlondikeInstruction → Saved* ─────────────────────────────────
-
-impl From<Tableau> for SavedTableau {
-    fn from(t: Tableau) -> Self {
-        Self(t as u8)
+/// 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,
    }
 }

-impl From<Foundation> for SavedFoundation {
-    fn from(f: Foundation) -> Self {
-        Self(f as u8)
+/// 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,
    }
 }
-
-impl From<SkipCards> for SavedSkipCards {
-    fn from(s: SkipCards) -> Self {
-        Self(s as u8)
-    }
-}
-
-impl From<KlondikePile> for SavedKlondikePile {
-    fn from(p: KlondikePile) -> Self {
-        match p {
-            KlondikePile::Tableau(t) => Self::Tableau(t.into()),
-            KlondikePile::Stock => Self::Stock,
-            KlondikePile::Foundation(f) => Self::Foundation(f.into()),
-        }
-    }
-}
-
-impl From<TableauStack> for SavedTableauStack {
-    fn from(ts: TableauStack) -> Self {
-        Self { tableau: ts.tableau.into(), skip_cards: ts.skip_cards.into() }
-    }
-}
-
-impl From<KlondikePileStack> for SavedKlondikePileStack {
-    fn from(ps: KlondikePileStack) -> Self {
-        match ps {
-            KlondikePileStack::Tableau(ts) => Self::Tableau(ts.into()),
-            KlondikePileStack::Stock => Self::Stock,
-            KlondikePileStack::Foundation(f) => Self::Foundation(f.into()),
-        }
-    }
-}
-
-impl From<DstFoundation> for SavedDstFoundation {
-    fn from(df: DstFoundation) -> Self {
-        Self { src: df.src.into(), foundation: df.foundation.into() }
-    }
-}
-
-impl From<DstTableau> for SavedDstTableau {
-    fn from(dt: DstTableau) -> Self {
-        Self { src: dt.src.into(), tableau: dt.tableau.into() }
-    }
-}
-
-impl From<KlondikeInstruction> for SavedInstruction {
-    fn from(i: KlondikeInstruction) -> Self {
-        match i {
-            KlondikeInstruction::RotateStock => Self::RotateStock,
-            KlondikeInstruction::DstFoundation(df) => Self::DstFoundation(df.into()),
-            KlondikeInstruction::DstTableau(dt) => Self::DstTableau(dt.into()),
-        }
-    }
-}
-
-// ── TryFrom impls: Saved* → KlondikeInstruction ──────────────────────────────
-
-impl TryFrom<SavedTableau> for Tableau {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedTableau) -> Result<Self, Self::Error> {
-        match s.0 {
-            0 => Ok(Tableau::Tableau1),
-            1 => Ok(Tableau::Tableau2),
-            2 => Ok(Tableau::Tableau3),
-            3 => Ok(Tableau::Tableau4),
-            4 => Ok(Tableau::Tableau5),
-            5 => Ok(Tableau::Tableau6),
-            6 => Ok(Tableau::Tableau7),
-            n => Err(InvalidSavedInstruction::Tableau(n)),
-        }
-    }
-}
-
-impl TryFrom<SavedFoundation> for Foundation {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedFoundation) -> Result<Self, Self::Error> {
-        match s.0 {
-            0 => Ok(Foundation::Foundation1),
-            1 => Ok(Foundation::Foundation2),
-            2 => Ok(Foundation::Foundation3),
-            3 => Ok(Foundation::Foundation4),
-            n => Err(InvalidSavedInstruction::Foundation(n)),
-        }
-    }
-}
-
-impl TryFrom<SavedSkipCards> for SkipCards {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedSkipCards) -> Result<Self, Self::Error> {
-        match s.0 {
-            0 => Ok(SkipCards::Skip0),
-            1 => Ok(SkipCards::Skip1),
-            2 => Ok(SkipCards::Skip2),
-            3 => Ok(SkipCards::Skip3),
-            4 => Ok(SkipCards::Skip4),
-            5 => Ok(SkipCards::Skip5),
-            6 => Ok(SkipCards::Skip6),
-            7 => Ok(SkipCards::Skip7),
-            8 => Ok(SkipCards::Skip8),
-            9 => Ok(SkipCards::Skip9),
-            10 => Ok(SkipCards::Skip10),
-            11 => Ok(SkipCards::Skip11),
-            12 => Ok(SkipCards::Skip12),
-            n => Err(InvalidSavedInstruction::SkipCards(n)),
-        }
-    }
-}
-
-impl TryFrom<SavedKlondikePile> for KlondikePile {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedKlondikePile) -> Result<Self, Self::Error> {
-        Ok(match s {
-            SavedKlondikePile::Tableau(t) => KlondikePile::Tableau(t.try_into()?),
-            SavedKlondikePile::Stock => KlondikePile::Stock,
-            SavedKlondikePile::Foundation(f) => KlondikePile::Foundation(f.try_into()?),
-        })
-    }
-}
-
-impl TryFrom<SavedTableauStack> for TableauStack {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedTableauStack) -> Result<Self, Self::Error> {
-        Ok(TableauStack {
-            tableau: s.tableau.try_into()?,
-            skip_cards: s.skip_cards.try_into()?,
-        })
-    }
-}
-
-impl TryFrom<SavedKlondikePileStack> for KlondikePileStack {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedKlondikePileStack) -> Result<Self, Self::Error> {
-        Ok(match s {
-            SavedKlondikePileStack::Tableau(ts) => KlondikePileStack::Tableau(ts.try_into()?),
-            SavedKlondikePileStack::Stock => KlondikePileStack::Stock,
-            SavedKlondikePileStack::Foundation(f) => {
-                KlondikePileStack::Foundation(f.try_into()?)
-            }
-        })
-    }
-}
-
-impl TryFrom<SavedDstFoundation> for DstFoundation {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedDstFoundation) -> Result<Self, Self::Error> {
-        Ok(DstFoundation { src: s.src.try_into()?, foundation: s.foundation.try_into()? })
-    }
-}
-
-impl TryFrom<SavedDstTableau> for DstTableau {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedDstTableau) -> Result<Self, Self::Error> {
-        Ok(DstTableau { src: s.src.try_into()?, tableau: s.tableau.try_into()? })
-    }
-}
-
-impl TryFrom<SavedInstruction> for KlondikeInstruction {
-    type Error = InvalidSavedInstruction;
-    fn try_from(s: SavedInstruction) -> Result<Self, Self::Error> {
-        Ok(match s {
-            SavedInstruction::RotateStock => KlondikeInstruction::RotateStock,
-            SavedInstruction::DstFoundation(df) => {
-                KlondikeInstruction::DstFoundation(df.try_into()?)
-            }
-            SavedInstruction::DstTableau(dt) => KlondikeInstruction::DstTableau(dt.try_into()?),
-        })
-    }
-}
-
-/// 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.
-pub fn compute_time_bonus(elapsed_seconds: u64) -> i32 {
-    if elapsed_seconds == 0 {
-        return 0;
-    }
-    (700_000u64 / elapsed_seconds).min(i32::MAX as u64) as i32
-}
@@ -1,7 +1,23 @@
 pub mod achievement;
-pub mod card;
 pub mod error;
 pub mod game_state;
 pub mod klondike_adapter;
-pub mod pile;
-pub mod solver;
+pub mod scoring;
+
+// 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,108 +0,0 @@
-use crate::card::{Card, Suit};
-use klondike::KlondikePile;
-
-/// A named collection of cards in a specific board position.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct Pile {
-    /// Which logical Klondike pile this is.
-    pub pile_type: KlondikePile,
-    /// 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: KlondikePile) -> 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 {
-            KlondikePile::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(KlondikePile::Stock);
-        assert!(pile.cards.is_empty());
-    }
-
-    #[test]
-    fn pile_top_returns_last_card() {
-        let mut pile = Pile::new(KlondikePile::Stock);
-        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(KlondikePile::Stock);
-        assert!(pile.top().is_none());
-    }
-
-    #[test]
-    fn claimed_suit_is_none_for_empty_foundation() {
-        let pile = Pile::new(KlondikePile::Foundation(klondike::Foundation::Foundation1));
-        assert!(pile.claimed_suit().is_none());
-    }
-
-    #[test]
-    fn claimed_suit_is_none_for_non_foundation() {
-        let mut pile = Pile::new(KlondikePile::Tableau(klondike::Tableau::Tableau1));
-        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(KlondikePile::Foundation(klondike::Foundation::Foundation3));
-        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:?}",
+            );
+        }
+    }
+
+}
@@ -0,0 +1,15 @@
+//! 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.
+pub fn compute_time_bonus(elapsed_seconds: u64) -> i32 {
+    if elapsed_seconds == 0 {
+        return 0;
+    }
+    (700_000u64 / elapsed_seconds).min(i32::MAX as u64) as i32
+}
@@ -1,345 +0,0 @@
-//! Klondike solvability checker using deterministic DFS over [`GameState`].
-//!
-//! Used by the engine to back the **Settings → Gameplay → "Winnable deals only"**
-//! toggle and by the hint system when it wants the first move on a winning path.
-
-use std::collections::HashSet;
-
-use klondike::{Foundation, KlondikePile, Tableau};
-
-use crate::card::Card;
-use crate::game_state::{DifficultyLevel, DrawMode, GameMode, GameState};
-
-/// Verdict returned by [`try_solve`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum SolverResult {
-    /// The solver found a sequence of moves that wins the deal.
-    Winnable,
-    /// The solver exhaustively searched and confirmed no win exists.
-    Unwinnable,
-    /// The move / state budget was exceeded before a verdict could be reached.
-    Inconclusive,
-}
-
-/// Tunable budgets controlling how long [`try_solve`] is willing to search.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct SolverConfig {
-    /// Maximum total moves to consider across the entire search tree.
-    pub move_budget: u64,
-    /// Maximum unique states to visit.
-    pub state_budget: usize,
-}
-
-impl Default for SolverConfig {
-    fn default() -> Self {
-        Self {
-            move_budget: 100_000,
-            state_budget: 200_000,
-        }
-    }
-}
-
-/// A single move the solver can recommend, expressed in engine-level pile terms.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SolverMove {
-    /// Pile the move originates from.
-    pub source: KlondikePile,
-    /// Pile the move lands on.
-    pub dest: KlondikePile,
-    /// Number of cards in the move (1 for non-tableau-to-tableau moves).
-    pub count: usize,
-}
-
-/// Solver verdict plus, when winnable, the first move on a winning path.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SolveOutcome {
-    /// The high-level verdict (Winnable / Unwinnable / Inconclusive).
-    pub result: SolverResult,
-    /// First move on the solution path when `result == Winnable`.
-    pub first_move: Option<SolverMove>,
-}
-
-#[derive(Debug, Clone)]
-struct DfsFrame {
-    state: GameState,
-    moves: Vec<SolverMove>,
-    next_index: usize,
-    first_move: Option<SolverMove>,
-}
-
-/// Tries to solve a fresh Classic-mode game from `seed` + `draw_mode`.
-pub fn try_solve(seed: u64, draw_mode: DrawMode, config: &SolverConfig) -> SolverResult {
-    try_solve_with_first_move(seed, draw_mode, config).result
-}
-
-/// Tries to solve a fresh Classic-mode game and, when winnable, returns the
-/// first move on a winning path.
-///
-/// Fresh-deal solving models standard Klondike rules, so the non-standard
-/// take-from-foundation house rule stays disabled here.
-pub fn try_solve_with_first_move(
-    seed: u64,
-    draw_mode: DrawMode,
-    config: &SolverConfig,
-) -> SolveOutcome {
-    let mut game = GameState::new(seed, draw_mode);
-    game.take_from_foundation = false;
-    solve_game_state(&game, config)
-}
-
-/// Tries to solve from an existing in-progress [`GameState`].
-pub fn try_solve_from_state(state: &GameState, config: &SolverConfig) -> SolveOutcome {
-    solve_game_state(state, config)
-}
-
-fn solve_game_state(initial: &GameState, config: &SolverConfig) -> SolveOutcome {
-    // Keep solver latency bounded even when callers pass very large budgets.
-    // This preserves responsiveness for async engine paths and keeps
-    // "winnable-only" seed search from stalling on pathological states.
-    let effective_state_budget = config.state_budget.min(5_000);
-    let effective_move_budget = config.move_budget.min(5_000);
-
-    if effective_state_budget == 0 {
-        return SolveOutcome {
-            result: SolverResult::Inconclusive,
-            first_move: None,
-        };
-    }
-    // Preserve the historical payload contract: winnable verdicts always carry
-    // a first move. An already-won state therefore returns no recommendation.
-    if initial.is_won {
-        return SolveOutcome {
-            result: SolverResult::Unwinnable,
-            first_move: None,
-        };
-    }
-
-    let mut visited: HashSet<Vec<u32>> = HashSet::with_capacity(effective_state_budget.min(16_384));
-    visited.insert(state_key(initial));
-
-    let mut states_visited: usize = 1;
-    let mut moves_considered: u64 = 0;
-    let mut saw_inconclusive = false;
-
-    let mut stack = vec![DfsFrame {
-        state: initial.clone(),
-        moves: candidate_moves(initial),
-        next_index: 0,
-        first_move: None,
-    }];
-
-    while let Some(frame) = stack.last_mut() {
-        if frame.state.is_won {
-            if let Some(first_move) = frame.first_move.clone() {
-                return SolveOutcome {
-                    result: SolverResult::Winnable,
-                    first_move: Some(first_move),
-                };
-            }
-            stack.pop();
-            continue;
-        }
-
-        if frame.next_index >= frame.moves.len() {
-            stack.pop();
-            continue;
-        }
-
-        if moves_considered >= effective_move_budget {
-            saw_inconclusive = true;
-            break;
-        }
-
-        let next_move = frame.moves[frame.next_index].clone();
-        frame.next_index += 1;
-        moves_considered = moves_considered.saturating_add(1);
-
-        let Some(next_state) = apply_solver_move(&frame.state, &next_move) else {
-            continue;
-        };
-
-        let key = state_key(&next_state);
-        if visited.contains(&key) {
-            continue;
-        }
-        if states_visited >= effective_state_budget {
-            saw_inconclusive = true;
-            continue;
-        }
-
-        visited.insert(key);
-        states_visited = states_visited.saturating_add(1);
-
-        let first_move = frame
-            .first_move
-            .clone()
-            .or_else(|| Some(next_move.clone()));
-        let child_moves = candidate_moves(&next_state);
-        stack.push(DfsFrame {
-            state: next_state,
-            moves: child_moves,
-            next_index: 0,
-            first_move,
-        });
-    }
-
-    if saw_inconclusive {
-        SolveOutcome {
-            result: SolverResult::Inconclusive,
-            first_move: None,
-        }
-    } else {
-        SolveOutcome {
-            result: SolverResult::Unwinnable,
-            first_move: None,
-        }
-    }
-}
-
-fn candidate_moves(game: &GameState) -> Vec<SolverMove> {
-    let mut out: Vec<SolverMove> = game
-        .possible_instructions()
-        .into_iter()
-        .map(|(source, dest, count)| SolverMove {
-            source,
-            dest,
-            count,
-        })
-        .collect();
-
-    if !game.stock_cards().is_empty() || !game.waste_cards().is_empty() {
-        out.push(SolverMove {
-            source: KlondikePile::Stock,
-            dest: KlondikePile::Stock,
-            count: 1,
-        });
-    }
-
-    out
-}
-
-fn apply_solver_move(game: &GameState, mv: &SolverMove) -> Option<GameState> {
-    let mut next = game.clone();
-    if mv.source == KlondikePile::Stock && mv.dest == KlondikePile::Stock {
-        next.draw().ok()?;
-    } else {
-        next.move_cards(mv.source, mv.dest, mv.count).ok()?;
-    }
-    Some(next)
-}
-
-fn state_key(game: &GameState) -> Vec<u32> {
-    let mut key = Vec::with_capacity(96);
-
-    append_pile_key(&game.stock_cards(), &mut key);
-    append_pile_key(&game.waste_cards(), &mut key);
-
-    for foundation in [
-        Foundation::Foundation1,
-        Foundation::Foundation2,
-        Foundation::Foundation3,
-        Foundation::Foundation4,
-    ] {
-        append_pile_key(&game.pile(KlondikePile::Foundation(foundation)), &mut key);
-    }
-
-    for tableau in [
-        Tableau::Tableau1,
-        Tableau::Tableau2,
-        Tableau::Tableau3,
-        Tableau::Tableau4,
-        Tableau::Tableau5,
-        Tableau::Tableau6,
-        Tableau::Tableau7,
-    ] {
-        append_pile_key(&game.pile(KlondikePile::Tableau(tableau)), &mut key);
-    }
-
-    key.push(game.draw_mode as u32);
-    key.push(mode_key(game.mode));
-    key.push(u32::from(game.take_from_foundation));
-    key
-}
-
-fn append_pile_key(cards: &[Card], key: &mut Vec<u32>) {
-    key.push(cards.len() as u32);
-    for card in cards {
-        key.push((card.id << 1) | u32::from(card.face_up));
-    }
-}
-
-fn mode_key(mode: GameMode) -> u32 {
-    match mode {
-        GameMode::Classic => 0,
-        GameMode::Zen => 1,
-        GameMode::Challenge => 2,
-        GameMode::TimeAttack => 3,
-        GameMode::Difficulty(level) => match level {
-            DifficultyLevel::Easy => 10,
-            DifficultyLevel::Medium => 11,
-            DifficultyLevel::Hard => 12,
-            DifficultyLevel::Expert => 13,
-            DifficultyLevel::Grandmaster => 14,
-            DifficultyLevel::Random => 15,
-        },
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn try_solve_with_first_move_is_deterministic() {
-        let config = SolverConfig::default();
-        let a = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        let b = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        let c = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        assert_eq!(a, b);
-        assert_eq!(b, c);
-    }
-
-    #[test]
-    fn try_solve_with_first_move_returns_consistent_payload() {
-        let config = SolverConfig {
-            move_budget: 5_000,
-            state_budget: 5_000,
-        };
-        let outcome = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        match outcome.result {
-            SolverResult::Winnable => assert!(outcome.first_move.is_some()),
-            SolverResult::Unwinnable | SolverResult::Inconclusive => {
-                assert!(outcome.first_move.is_none())
-            }
-        }
-    }
-
-    #[test]
-    fn try_solve_from_state_uses_live_game_state() {
-        let mut game = GameState::new(42, DrawMode::DrawOne);
-        game.draw().expect("draw must succeed");
-
-        let config = SolverConfig {
-            move_budget: 5_000,
-            state_budget: 5_000,
-        };
-        let outcome = try_solve_from_state(&game, &config);
-        match outcome.result {
-            SolverResult::Winnable => assert!(outcome.first_move.is_some()),
-            SolverResult::Unwinnable | SolverResult::Inconclusive => {
-                assert!(outcome.first_move.is_none())
-            }
-        }
-    }
-
-    #[test]
-    fn zero_state_budget_is_inconclusive() {
-        let config = SolverConfig {
-            move_budget: 5_000,
-            state_budget: 0,
-        };
-        let outcome = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        assert_eq!(outcome.result, SolverResult::Inconclusive);
-        assert!(outcome.first_move.is_none());
-    }
-}
@@ -7,13 +7,14 @@ 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 }
-klondike       = { workspace = true }

 # These deps are not available / not needed on wasm32:
 #   dirs     — platform data directories (no filesystem on browser)
@@ -36,12 +37,9 @@ 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 }
@@ -49,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,6 +143,9 @@ 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;

@@ -161,11 +164,14 @@ 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;
@@ -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");
+    }
+}
@@ -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::klondike_adapter::SavedKlondikePile;
+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: SavedKlondikePile,
-        /// Destination pile.
-        to: SavedKlondikePile,
-        /// 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,7 +429,9 @@ pub fn migrate_legacy_latest_replay(latest_path: &Path, history_path: &Path) {
 #[allow(deprecated)]
 mod tests {
    use super::*;
-    use solitaire_core::klondike_adapter::{SavedFoundation, SavedTableau};
+    use klondike::{
+        DstFoundation, DstTableau, Foundation, KlondikePile, KlondikePileStack, Tableau,
+    };
    use std::env;

    fn tmp_path(name: &str) -> PathBuf {
@@ -453,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: SavedKlondikePile::Stock,
-                    to: SavedKlondikePile::Tableau(SavedTableau(3)),
-                    count: 1,
-                },
-                ReplayMove::StockClick,
-                ReplayMove::Move {
-                    from: SavedKlondikePile::Tableau(SavedTableau(3)),
-                    to: SavedKlondikePile::Foundation(SavedFoundation(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,
+                }),
            ],
        )
    }
@@ -596,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],
        )
    }

@@ -837,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",
@@ -847,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 chrono::Utc;

 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() {
@@ -282,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 {
@@ -295,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);
@@ -380,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]
@@ -409,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(),
@@ -424,9 +421,9 @@ mod tests {

    #[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");
@@ -442,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");
@@ -495,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,9 +12,9 @@
 //! without matching on [`SyncBackend`] anywhere else in the codebase.

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

 use crate::{SyncError, SyncProvider};

@@ -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,
        }
    }

@@ -10,7 +10,6 @@ image          = { workspace = true }
 solitaire_core = { workspace = true }
 solitaire_data = { workspace = true }
 solitaire_sync = { workspace = true }
-klondike       = { workspace = true }
 chrono         = { workspace = true }
 uuid           = { workspace = true }
 serde          = { workspace = true }
@@ -52,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}"))
+    })
 }
@@ -354,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,
@@ -1078,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 klondike::{KlondikePile, Tableau};
+        use solitaire_core::{KlondikePile, Tableau};
        let mut app = App::new();
        app.add_plugins(MinimalPlugins).add_plugins(AnimationPlugin);

@@ -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).
@@ -115,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"),
@@ -172,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"),
@@ -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>();
    }
 }
@@ -373,9 +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()
-            .map_or(1, |g| g.0.stock_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();
@@ -51,15 +51,15 @@ impl Plugin for AutoCompletePlugin {
        app.init_resource::<AutoCompleteState>()
            .add_message::<RequestRedraw>()
            .add_systems(
-            Update,
-            (
-                detect_auto_complete,
-                on_auto_complete_start,
-                drive_auto_complete,
-            )
-                .chain()
-                .after(GameMutation),
-        );
+                Update,
+                (
+                    detect_auto_complete,
+                    on_auto_complete_start,
+                    drive_auto_complete,
+                )
+                    .chain()
+                    .after(GameMutation),
+            );
    }
 }

@@ -76,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 = 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.
@@ -160,9 +167,9 @@ mod tests {
    use super::*;
    use crate::game_plugin::GamePlugin;
    use crate::table_plugin::TablePlugin;
-    use klondike::{Foundation, KlondikePile, Tableau};
-    use solitaire_core::card::{Rank, Suit};
-    use solitaire_core::game_state::{DrawMode, GameState};
+    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();
@@ -170,13 +177,13 @@ 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
    }

    fn seeded_state_with_auto_move() -> (GameState, (KlondikePile, KlondikePile)) {
-        let mut g = GameState::new(1, DrawMode::DrawOne);
+        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 [
@@ -200,14 +207,9 @@ mod tests {
        }
        g.set_test_tableau_cards(
            Tableau::Tableau1,
-            vec![solitaire_core::card::Card {
-                id: 7_001,
-                suit: Suit::Clubs,
-                rank: Rank::Ace,
-                face_up: true,
-            }],
+            vec![solitaire_core::Card::new(Deck::Deck1, Suit::Clubs, Rank::Ace)],
        );
-        g.is_auto_completable = true;
+        g.set_test_auto_completable(true);
        let expected = (
            KlondikePile::Tableau(Tableau::Tableau1),
            KlondikePile::Foundation(Foundation::Foundation1),
@@ -225,8 +227,8 @@ mod tests {
    #[test]
    fn detect_activates_when_auto_completable() {
        let mut app = headless_app();
-        let mut g = GameState::new(42, DrawMode::DrawOne);
-        g.is_auto_completable = true;
+        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();
@@ -244,9 +246,7 @@ mod tests {

        // 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.world_mut().resource_mut::<AutoCompleteState>().cooldown = 0.0;
        app.update(); // drive fires the move

        let events = app.world().resource::<Messages<MoveRequestEvent>>();
@@ -263,7 +263,7 @@ mod tests {
        let mut app = headless_app();
        // Inject a won game state — active should not be set.
        let (mut gs, _) = seeded_state_with_auto_move();
-        gs.is_won = true;
+        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);
@@ -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,
@@ -34,8 +34,9 @@

 use bevy::prelude::*;
 use bevy::window::{CursorIcon, PrimaryWindow, SystemCursorIcon};
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::game_state::{DrawMode, GameState};
+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};
@@ -79,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,
            ),
        );
@@ -185,7 +186,7 @@ fn cursor_over_draggable(cursor: Vec2, game: &GameState, layout: &Layout) -> boo
        let base = layout.pile_positions[&pile];

        for (i, card) in pile_cards.iter().enumerate().rev() {
-            if !card.face_up {
+            if !card.1 {
                continue;
            }
            // Only the topmost card is draggable on non-tableau piles.
@@ -331,7 +332,11 @@ 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: &KlondikePile, 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, KlondikePile::Tableau(_)) {
        let card_count = game.pile(*pile).len();
@@ -432,7 +437,7 @@ fn tableau_or_stack_pos(
            base.x,
            base.y - layout.card_size.y * layout.tableau_fan_frac * (index as f32),
        )
-    } else if matches!(pile, KlondikePile::Stock) && game.draw_mode == DrawMode::DrawThree {
+    } 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;
@@ -442,7 +447,7 @@ fn tableau_or_stack_pos(
    }
 }

-fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<solitaire_core::card::Card> {
+fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(Card, bool)> {
    if matches!(pile, KlondikePile::Stock) {
        game.waste_cards()
    } else {
@@ -558,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(
@@ -575,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
@@ -614,33 +619,23 @@ mod tests {
            game.0.set_test_waste_cards(vec![dragged.clone()]);
        }
        let mut drag = app.world_mut().resource_mut::<DragState>();
-        drag.cards = vec![dragged.id];
+        drag.cards = vec![dragged];
        drag.origin_pile = Some(KlondikePile::Stock);
        drag.committed = true;
    }

-        #[test]
+    #[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);
@@ -651,12 +646,11 @@ mod tests {
            .world_mut()
            .query::<&DropTargetOverlay>()
            .iter(app.world())
-            .map(|o| o.0.clone())
+            .map(|o| o.0)
            .collect();
        assert!(
            !overlays.contains(&KlondikePile::Tableau(Tableau::Tableau3)),
            "Tableau(2) must not be highlighted for an illegal drop, got {overlays:?}"
        );
    }
-
-    }
+}
@@ -13,10 +13,10 @@

 use bevy::input::ButtonInput;
 use bevy::prelude::*;
-use chrono::{DateTime, Duration, Local, NaiveDate, Utc};
-use solitaire_data::{daily_seed_for, save_progress_to};
 #[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;

@@ -354,7 +354,6 @@ fn check_date_rollover(
    }
 }

-
 #[cfg(test)]
 #[allow(dead_code)]
 mod tests {
@@ -363,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();
@@ -392,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,
@@ -420,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,
@@ -443,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,
@@ -1,8 +1,8 @@
 //! Cross-system events used by the engine's plugins.

 use bevy::prelude::Message;
-use klondike::KlondikePile;
-use solitaire_core::card::Suit;
+use solitaire_core::KlondikePile;
+use solitaire_core::{Card, Suit};
 use solitaire_core::game_state::GameMode;
 use solitaire_data::AchievementRecord;
 use solitaire_sync::SyncResponse;
@@ -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: KlondikePile,
 }
@@ -43,7 +43,9 @@ use std::hash::{Hash, Hasher};

 use bevy::prelude::*;
 use bevy::window::RequestRedraw;
-use klondike::{Foundation, KlondikePile};
+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;
@@ -245,16 +247,16 @@ fn start_shake_anim(
            continue;
        }
        let dest_pile = &ev.to;
-        // Collect the card ids that belong to the destination pile.
+        // Collect the cards that belong to the destination pile.
        let dest_cards = pile_cards(&game.0, dest_pile);
-        let dest_card_ids: Vec<u32> = dest_cards.iter().map(|c| c.id).collect();
+        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() {
        let pile = pile_cards(&game.0, &ev.to);
        if !pile.is_empty() {
-            // The moved cards land on top — take the last `count` ids.
+            // The moved cards land on top — take the last `count` cards.
            let n = ev.count.min(pile.len());
            if n > 0 {
                let start = pile.len() - n;
-                bounce_ids.extend(pile[start..].iter().map(|c| c.id));
+                bounce_ids.extend(pile[start..].iter().map(|(c, _)| c.clone()));
            }
        }
    }

    if draws.read().next().is_some()
-        && let Some(top) = game.0.waste_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,7 +395,7 @@ 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 };
@@ -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 {
@@ -524,13 +530,13 @@ fn start_foundation_flourish(
        let pile_type = KlondikePile::Foundation(foundation);
        // Top card of the completed foundation is the King.
        let cards = game.0.pile(pile_type);
-        let Some(king_id) = cards.last().map(|c| c.id) else {
+        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,
@@ -633,23 +639,13 @@ fn lerp_color(from: Color, to: Color, t: f32) -> Color {
 fn pile_cards(
    game: &solitaire_core::game_state::GameState,
    pile: &KlondikePile,
-) -> Vec<solitaire_core::card::Card> {
+) -> Vec<(Card, bool)> {
    match pile {
        KlondikePile::Stock => game.waste_cards(),
        _ => game.pile(*pile),
    }
 }

-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,
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Unit tests (pure functions only — no Bevy world required)
 // ---------------------------------------------------------------------------
@@ -849,14 +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 klondike::Tableau;
+        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()
@@ -865,19 +861,19 @@ mod tests {

        // Pick a card from Tableau(0) so the event refers to a real pile.
        let dest_pile = KlondikePile::Tableau(Tableau::Tableau1);
-        let card_id = app
+        let card = app
            .world()
            .resource::<GameStateResource>()
            .0
            .pile(dest_pile)
            .last()
-            .map(|c| c.id)
+            .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>>()
@@ -904,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()
@@ -921,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::*;

@@ -13,13 +13,13 @@ use chrono::Utc;
 use bevy::prelude::*;
 use bevy::tasks::{AsyncComputeTaskPool, Task, futures_lite::future};
 use bevy::window::AppLifecycle;
-use solitaire_core::game_state::{DrawMode, GameMode, GameState};
-use klondike::KlondikePile;
-use solitaire_core::solver::{SolverConfig, SolverResult, try_solve};
+use solitaire_core::KlondikePile;
+use solitaire_core::{DrawStockConfig, game_state::{GameMode, GameState}};
+use solitaire_core::{DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET, KlondikeInstruction};
 #[allow(deprecated)]
 use solitaire_data::latest_replay_path;
 use solitaire_data::{
-    Replay, ReplayMove, SOLVER_DEAL_RETRY_CAP, append_replay_to_history, delete_game_state_at,
+    Replay, SOLVER_DEAL_RETRY_CAP, append_replay_to_history, delete_game_state_at,
    game_state_file_path, load_game_state_from, migrate_legacy_latest_replay, replay_history_path,
    save_game_state_to,
 };
@@ -105,18 +105,21 @@ pub struct RestoreContinueButton;
 #[derive(Component, Debug)]
 pub struct RestoreNewGameButton;

-/// In-memory accumulator for [`ReplayMove`] entries during the current
-/// game. Cleared on every new-game start; frozen into a [`Replay`] and
-/// flushed to disk by [`record_replay_on_win`] when the player wins.
+/// In-memory accumulator for [`KlondikeInstruction`] entries during the
+/// current game. Cleared on every new-game start; frozen into a [`Replay`]
+/// and flushed to disk by [`record_replay_on_win`] when the player wins.
 ///
 /// Recording captures only successful state-mutating events the player
 /// drove (`MoveRequestEvent`, `DrawRequestEvent`). `UndoRequestEvent` is
 /// intentionally not recorded — see [`solitaire_data::replay`] for the
-/// design rationale.
+/// design rationale. Each entry is the atomic player input as a
+/// [`KlondikeInstruction`] (a stock click is
+/// [`KlondikeInstruction::RotateStock`]); pile-position types are
+/// runtime-only and never persisted.
 #[derive(Resource, Debug, Default, Clone)]
 pub struct RecordingReplay {
-    /// Ordered list of moves applied so far this game.
-    pub moves: Vec<ReplayMove>,
+    /// Ordered list of instructions applied so far this game.
+    pub moves: Vec<KlondikeInstruction>,
 }

 impl RecordingReplay {
@@ -154,15 +157,15 @@ impl Plugin for GamePlugin {
        let saved = path.as_deref().and_then(load_game_state_from);
        let prompt_worthy = saved
            .as_ref()
-            .is_some_and(|g| g.move_count > 0 && !g.is_won);
+            .is_some_and(|g| g.move_count() > 0 && !g.is_won());
        let (initial_state, pending_restore) = if prompt_worthy {
            (
-                GameState::new(seed_from_system_time(), DrawMode::DrawOne),
+                GameState::new(seed_from_system_time(), DrawStockConfig::DrawOne),
                saved,
            )
        } else {
            (
-                saved.unwrap_or_else(|| GameState::new(seed_from_system_time(), DrawMode::DrawOne)),
+                saved.unwrap_or_else(|| GameState::new(seed_from_system_time(), DrawStockConfig::DrawOne)),
                None,
            )
        };
@@ -198,7 +201,7 @@ impl Plugin for GamePlugin {
            .add_message::<StateChangedEvent>()
            .add_message::<crate::events::MoveRejectedEvent>()
            .add_message::<GameWonEvent>()
-            .add_message::<crate::events::CardFlippedEvent>()
+            .add_message::<CardFlippedEvent>()
            .add_message::<crate::events::AchievementUnlockedEvent>()
            .add_message::<FoundationCompletedEvent>()
            .add_message::<InfoToastEvent>()
@@ -302,7 +305,7 @@ fn tick_elapsed_time(
        *skip_next_delta = false;
        return;
    }
-    let is_won = game.0.is_won;
+    let is_won = game.0.is_won();
    advance_elapsed(
        &mut game.0.elapsed_seconds,
        &mut accumulator,
@@ -316,18 +319,18 @@ fn seed_from_system_time() -> u64 {
 }

 /// Walks forward from `initial_seed` (incrementing by 1 with wrapping
-/// arithmetic) until the [`solitaire_core::solver`] returns a verdict
+/// arithmetic) until the [`GameState::solve_fresh_deal`] returns a verdict
 /// the engine accepts as winnable, or until [`SOLVER_DEAL_RETRY_CAP`]
 /// attempts have elapsed.
 ///
 /// The solver classifies each deal as one of three verdicts:
-///   - [`SolverResult::Winnable`] — provably solvable; accept.
-///   - [`SolverResult::Inconclusive`] — budget exceeded, no proof
-///     either way; accept (we treat "we don't know" as winnable so
-///     the toggle never silently drops a player into the retry cap).
-///   - [`SolverResult::Unwinnable`] — provably dead; try the next seed.
+///   - `Ok(Some(_))` — winnable (provably solvable); accept.
+///   - `Err(_)` — inconclusive (budget exceeded, no proof either way);
+///     accept (we treat "we don't know" as winnable so the toggle never
+///     silently drops a player into the retry cap).
+///   - `Ok(None)` — provably dead; try the next seed.
 ///
-/// If every seed in the retry window is `Unwinnable` (extremely
+/// If every seed in the retry window is provably dead (extremely
 /// unlikely on real inputs), the function returns the *last* tried
 /// seed so the player still gets a deal — better a possibly-unwinnable
 /// hand than an infinite loop.
@@ -388,13 +391,19 @@ fn poll_pending_new_game_seed(

 /// Pure helper extracted for testability — `new_game_with_solver_*`
 /// engine tests in the same file exercise this path.
-pub(crate) fn choose_winnable_seed(initial_seed: u64, draw_mode: DrawMode) -> u64 {
-    let cfg = SolverConfig::default();
+pub(crate) fn choose_winnable_seed(initial_seed: u64, draw_mode: DrawStockConfig) -> u64 {
    let mut seed = initial_seed;
    for _ in 0..SOLVER_DEAL_RETRY_CAP {
-        match try_solve(seed, draw_mode, &cfg) {
-            SolverResult::Winnable | SolverResult::Inconclusive => return seed,
-            SolverResult::Unwinnable => {
+        match GameState::solve_fresh_deal(
+            seed,
+            draw_mode,
+            DEFAULT_SOLVE_MOVES_BUDGET,
+            DEFAULT_SOLVE_STATES_BUDGET,
+        ) {
+            // Winnable (`Ok(Some)`) or inconclusive (`Err`) → accept as
+            // "probably winnable"; only a proven dead deal (`Ok(None)`) retries.
+            Ok(Some(_)) | Err(_) => return seed,
+            Ok(None) => {
                seed = seed.wrapping_add(1);
            }
        }
@@ -424,7 +433,7 @@ fn handle_new_game(
    for ev in new_game.read() {
        // If an active game is in progress, intercept and show a confirm dialog.
        // A game is "active" when moves have been made and it is not yet won.
-        let needs_confirm = game.0.move_count > 0 && !game.0.is_won;
+        let needs_confirm = game.0.move_count() > 0 && !game.0.is_won();
        // Skip confirmation if a ConfirmNewGameScreen already exists (prevents
        // duplicates) or if the event itself was already confirmed by the
        // player pressing Y on the modal — without the `confirmed` check the
@@ -464,7 +473,7 @@ fn handle_new_game(
        // where SettingsPlugin is not installed.
        let draw_mode = settings
            .as_ref()
-            .map_or_else(|| game.0.draw_mode, |s| s.0.draw_mode);
+            .map_or_else(|| game.0.draw_mode(), |s| s.0.draw_mode);
        let mode = ev.mode.unwrap_or(game.0.mode);

        // Solver-backed retry: when the player has opted in to
@@ -521,10 +530,7 @@ fn handle_new_game(
        // hides that information and reads naturally as "dealt from the
        // deck." Skipped when LayoutResource isn't present (headless tests).
        if let Some(layout) = layout.as_ref()
-            && let Some(stock) = layout
-                .0
-                .pile_positions
-                .get(&klondike::KlondikePile::Stock)
+            && let Some(stock) = layout.0.pile_positions.get(&KlondikePile::Stock)
        {
            for mut tx in &mut card_transforms {
                tx.translation.x = stock.x;
@@ -821,26 +827,26 @@ fn handle_draw(
        // so we can fire flip events after they land face-up in the waste.
        // Only relevant when stock is non-empty; a recycle moves waste back to
        // stock face-down, so no flip events are needed in that case.
-        let drawn_ids: Vec<u32> = {
+        let drawn_cards: Vec<solitaire_core::Card> = {
            let stock = game.0.stock_cards();
            if stock.is_empty() {
                Vec::new()
            } else {
-                let draw_count = match game.0.draw_mode {
-                    DrawMode::DrawOne => 1_usize,
-                    DrawMode::DrawThree => 3_usize,
+                let draw_count = match game.0.draw_mode() {
+                    DrawStockConfig::DrawOne => 1_usize,
+                    DrawStockConfig::DrawThree => 3_usize,
                };
                let n = stock.len();
                let take = n.min(draw_count);
-                stock[n - take..].iter().map(|c| c.id).collect()
+                stock[n - take..].iter().map(|c| c.0.clone()).collect()
            }
        };

        match game.0.draw() {
            Ok(()) => {
                // Fire a flip event for each card that moved from stock to waste.
-                for id in drawn_ids {
-                    flipped.write(CardFlippedEvent(id));
+                for card in drawn_cards {
+                    flipped.write(CardFlippedEvent(card));
                }
                // Record the atomic player input. Whether the engine
                // resolves this to a draw or a waste→stock recycle is
@@ -848,7 +854,7 @@ fn handle_draw(
                // the click happens — re-executing on the same starting
                // deal produces the same effect, so the input alone is
                // sufficient to recover the move on playback.
-                recording.moves.push(ReplayMove::StockClick);
+                recording.moves.push(KlondikeInstruction::RotateStock);
                changed.write(StateChangedEvent);
            }
            Err(e) => warn!("draw rejected: {e}"),
@@ -862,21 +868,21 @@ fn handle_move(
    mut game: ResMut<GameStateResource>,
    mut changed: MessageWriter<StateChangedEvent>,
    mut won: MessageWriter<GameWonEvent>,
-    mut flipped: MessageWriter<crate::events::CardFlippedEvent>,
+    mut flipped: MessageWriter<CardFlippedEvent>,
    mut foundation_done: MessageWriter<FoundationCompletedEvent>,
    mut recording: ResMut<RecordingReplay>,
    path: Option<Res<GameStatePath>>,
 ) {
    for ev in moves.read() {
-        let was_won = game.0.is_won;
+        let was_won = game.0.is_won();
        // Identify the card that will be exposed (and may flip face-up) by the move.
        // It's the card just below the bottom of the moving stack in the source pile.
        let source_cards = pile_cards(&game.0, &ev.from);
-        let flip_candidate_id = {
+        let flip_candidate = {
            let n = source_cards.len();
            if n > ev.count {
                let c = &source_cards[n - ev.count - 1];
-                if !c.face_up { Some(c.id) } else { None }
+                if !c.1 { Some(c.0.clone()) } else { None }
            } else {
                None
            }
@@ -886,18 +892,24 @@ fn handle_move(
                // Record the move in the in-flight replay buffer. Done
                // first so the entry is captured even if a subsequent
                // event-write or pile-lookup happens to bail out below.
-                recording.moves.push(ReplayMove::Move {
-                    from: ev.from.into(),
-                    to: ev.to.into(),
-                    count: ev.count,
-                });
+                // `move_cards` resolved the pile coordinates to a
+                // `KlondikeInstruction` and pushed it onto the session
+                // history; recover that exact instruction from the tail
+                // (no clone — the instruction is `Copy`). Pile-position
+                // types are runtime-only, so we persist the instruction
+                // rather than the (from, to, count) triple.
+                if let Some(instruction) =
+                    game.0.session().history().last().map(|s| *s.instruction())
+                {
+                    recording.moves.push(instruction);
+                }
                // Fire flip event if the candidate card is now face-up.
-                if let Some(fid) = flip_candidate_id
+                if let Some(fcard) = flip_candidate
                    && pile_cards(&game.0, &ev.from)
                        .last()
-                        .is_some_and(|c| c.id == fid && c.face_up)
+                        .is_some_and(|c| c.0 == fcard && c.1)
                {
-                    flipped.write(crate::events::CardFlippedEvent(fid));
+                    flipped.write(CardFlippedEvent(fcard));
                }
                // If this move landed on a foundation pile and that pile is
                // now complete (Ace → King, 13 cards), fire the per-suit
@@ -908,14 +920,14 @@ fn handle_move(
                if let KlondikePile::Foundation(slot) = ev.to
                    && let Some(slot) = foundation_slot(slot)
                    && game.0.pile(ev.to).len() == 13
-                    && let Some(suit) = game.0.pile(ev.to).first().map(|c| c.suit)
+                    && let Some(suit) = game.0.pile(ev.to).first().map(|c| c.0.suit())
                {
                    foundation_done.write(FoundationCompletedEvent { slot, suit });
                }
                changed.write(StateChangedEvent);
-                if !was_won && game.0.is_won {
+                if !was_won && game.0.is_won() {
                    won.write(GameWonEvent {
-                        score: game.0.score,
+                        score: game.0.score(),
                        time_seconds: game.0.elapsed_seconds,
                    });
                    // Delete the saved state — a won game should not be resumed.
@@ -989,7 +1001,7 @@ pub fn record_replay_on_win(
        let win_move_index = recording.moves.len().checked_sub(1);
        let replay = Replay::new(
            game.0.seed,
-            game.0.draw_mode,
+            game.0.draw_mode(),
            game.0.mode,
            ev.time_seconds,
            ev.score,
@@ -1010,19 +1022,19 @@ pub fn record_replay_on_win(
    }
 }

-fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<solitaire_core::card::Card> {
+fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(solitaire_core::Card, bool)> {
    match pile {
        KlondikePile::Stock => game.waste_cards(),
        _ => game.pile(*pile),
    }
 }

-fn foundation_slot(foundation: klondike::Foundation) -> Option<u8> {
+fn foundation_slot(foundation: solitaire_core::Foundation) -> Option<u8> {
    match foundation {
-        klondike::Foundation::Foundation1 => Some(0),
-        klondike::Foundation::Foundation2 => Some(1),
-        klondike::Foundation::Foundation3 => Some(2),
-        klondike::Foundation::Foundation4 => Some(3),
+        solitaire_core::Foundation::Foundation1 => Some(0),
+        solitaire_core::Foundation::Foundation2 => Some(1),
+        solitaire_core::Foundation::Foundation3 => Some(2),
+        solitaire_core::Foundation::Foundation4 => Some(3),
    }
 }

@@ -1047,17 +1059,11 @@ fn foundation_slot(foundation: klondike::Foundation) -> Option<u8> {
 /// previous heuristic incorrectly did (Quat hit this with 4 cards
 /// remaining and the game just sat there).
 pub fn has_legal_moves(game: &GameState) -> bool {
-    
-
    // Drawing from a non-empty stock, and recycling a non-empty waste back to
    // stock, are always legal moves in standard Klondike (unlimited recycles).
    // A game can only be genuinely stuck when both stock AND waste are exhausted.
-    let stock_empty = game
-        .stock_cards()
-        .is_empty();
-    let waste_empty = game
-        .waste_cards()
-        .is_empty();
+    let stock_empty = game.stock_cards().is_empty();
+    let waste_empty = game.waste_cards().is_empty();
    if !stock_empty || !waste_empty {
        return true;
    }
@@ -1102,13 +1108,13 @@ fn check_no_moves(

    // Despawn game-over overlay whenever moves become available again or game is won.
    let moves_ok = has_legal_moves(&game.0);
-    if moves_ok || game.0.is_won {
+    if moves_ok || game.0.is_won() {
        for entity in &game_over_screens {
            commands.entity(entity).despawn();
        }
    }

-    if game.0.is_won {
+    if game.0.is_won() {
        return;
    }

@@ -1118,7 +1124,7 @@ fn check_no_moves(
        // Only spawn the overlay if one does not already exist, and no other
        // modal scrim is currently open (global ModalScrim guard).
        if game_over_screens.is_empty() && scrims.is_empty() {
-            spawn_game_over_screen(&mut commands, game.0.score, font_res.as_deref());
+            spawn_game_over_screen(&mut commands, game.0.score(), font_res.as_deref());
        }
    }
 }
@@ -1191,7 +1197,10 @@ fn handle_game_over_input(

    if keys.just_pressed(KeyCode::KeyN) || keys.just_pressed(KeyCode::Escape) {
        // confirmed: true — the game is already stuck; no abandon-confirmation needed.
-        new_game.write(NewGameRequestEvent { confirmed: true, ..default() });
+        new_game.write(NewGameRequestEvent {
+            confirmed: true,
+            ..default()
+        });
    } else if keys.just_pressed(KeyCode::KeyU) {
        for entity in &screens {
            commands.entity(entity).despawn();
@@ -1219,7 +1228,10 @@ fn handle_game_over_button_input(
    }
    if new_game_buttons.iter().any(|i| *i == Interaction::Pressed) {
        // confirmed: true — the game is already stuck; no abandon-confirmation needed.
-        new_game.write(NewGameRequestEvent { confirmed: true, ..default() });
+        new_game.write(NewGameRequestEvent {
+            confirmed: true,
+            ..default()
+        });
    } else if undo_buttons.iter().any(|i| *i == Interaction::Pressed) {
        for entity in &screens {
            commands.entity(entity).despawn();
@@ -1251,7 +1263,7 @@ fn auto_save_game_state(
    // or there's a pending restore the player hasn't answered — saving
    // the fresh-deal placeholder we seeded GameStateResource with at
    // startup would clobber the real saved game on disk.
-    if paused.is_some_and(|p| p.0) || game.0.is_won || game.0.move_count == 0 || pending.0.is_some()
+    if paused.is_some_and(|p| p.0) || game.0.is_won() || game.0.move_count() == 0 || pending.0.is_some()
    {
        return;
    }
@@ -1297,8 +1309,7 @@ fn save_game_state_on_exit(
 #[cfg(test)]
 mod tests {
    use super::*;
-    use klondike::{Foundation, KlondikePile, Tableau};
-    use solitaire_core::klondike_adapter::{SavedKlondikePile, SavedTableau};
+    use solitaire_core::{Foundation, KlondikePile, Tableau};

    /// Build a minimal headless `App` with just `GamePlugin` installed.
    /// Disables persistence and overrides the seed so tests are deterministic
@@ -1321,7 +1332,7 @@ mod tests {
        app.insert_resource(PendingRestoredGame(None));
        // Override the system-time seed with a known value.
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(seed, DrawMode::DrawOne);
+            GameState::new(seed, DrawStockConfig::DrawOne);
        app
    }

@@ -1388,11 +1399,13 @@ mod tests {
    #[test]
    fn new_game_request_reseeds() {
        let mut app = test_app(1);
-        let before: Vec<u32> = app.world().resource::<GameStateResource>().0.pile(KlondikePile::Tableau(
-            Tableau::Tableau1,
-        ))
+        let before: Vec<solitaire_core::Card> = app
+            .world()
+            .resource::<GameStateResource>()
+            .0
+            .pile(KlondikePile::Tableau(Tableau::Tableau1))
            .iter()
-            .map(|c| c.id)
+            .map(|c| c.0.clone())
            .collect();

        app.world_mut().write_message(NewGameRequestEvent {
@@ -1402,11 +1415,13 @@ mod tests {
        });
        app.update();

-        let after: Vec<u32> = app.world().resource::<GameStateResource>().0.pile(KlondikePile::Tableau(
-            Tableau::Tableau1,
-        ))
+        let after: Vec<solitaire_core::Card> = app
+            .world()
+            .resource::<GameStateResource>()
+            .0
+            .pile(KlondikePile::Tableau(Tableau::Tableau1))
            .iter()
-            .map(|c| c.id)
+            .map(|c| c.0.clone())
            .collect();
        assert_ne!(before, after);
    }
@@ -1415,17 +1430,27 @@ mod tests {
    fn settings_changed_updates_take_from_foundation_flag() {
        let mut app = test_app(1);
        assert!(
-            app.world().resource::<GameStateResource>().0.take_from_foundation,
+            app.world()
+                .resource::<GameStateResource>()
+                .0
+                .take_from_foundation,
            "fresh game should inherit default take_from_foundation=true",
        );

-        let mut settings = solitaire_data::Settings::default();
-        settings.take_from_foundation = false;
+        let mut settings = solitaire_data::Settings {
+            take_from_foundation: false,
+            ..Default::default()
+        };
        app.world_mut()
-            .write_message(crate::settings_plugin::SettingsChangedEvent(settings.clone()));
+            .write_message(crate::settings_plugin::SettingsChangedEvent(
+                settings.clone(),
+            ));
        app.update();
        assert!(
-            !app.world().resource::<GameStateResource>().0.take_from_foundation,
+            !app.world()
+                .resource::<GameStateResource>()
+                .0
+                .take_from_foundation,
            "settings event must forward take_from_foundation=false into live game state",
        );

@@ -1434,7 +1459,10 @@ mod tests {
            .write_message(crate::settings_plugin::SettingsChangedEvent(settings));
        app.update();
        assert!(
-            app.world().resource::<GameStateResource>().0.take_from_foundation,
+            app.world()
+                .resource::<GameStateResource>()
+                .0
+                .take_from_foundation,
            "settings event must forward take_from_foundation=true into live game state",
        );
    }
@@ -1502,7 +1530,7 @@ mod tests {
    // Persistence tests
    // -----------------------------------------------------------------------

-    fn tmp_gs_path(name: &str) -> std::path::PathBuf {
+    fn tmp_gs_path(name: &str) -> PathBuf {
        std::env::temp_dir().join(format!("engine_test_gs_{name}.json"))
    }

@@ -1520,7 +1548,7 @@ mod tests {
        app.insert_resource(GameStatePath(Some(path.clone())));
        // Override the seed so we can verify it was written.
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(7654, DrawMode::DrawOne);
+            GameState::new(7654, DrawStockConfig::DrawOne);

        app.world_mut().write_message(AppExit::Success);
        app.update();
@@ -1539,7 +1567,7 @@ mod tests {

        let path = tmp_gs_path("new_game_delete");
        // Pre-create a saved file.
-        save_game_state_to(&path, &GameState::new(1, DrawMode::DrawOne)).unwrap();
+        save_game_state_to(&path, &GameState::new(1, DrawStockConfig::DrawOne)).unwrap();
        assert!(path.exists());

        let mut app = test_app(1);
@@ -1557,7 +1585,7 @@ mod tests {
        );
    }

-        /// auto_save_game_state writes to disk once the accumulator crosses 30 s.
+    /// auto_save_game_state writes to disk once the accumulator crosses 30 s.
    ///
    /// The timer is pre-seeded just past the threshold and the test
    /// re-arms it before each `app.update()` in a small bounded loop:
@@ -1582,7 +1610,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .move_count = 1;
+            .set_test_move_count(1);

        // Re-arm the timer past the threshold every frame and pump
        // updates until the save fires. Caps at 16 iterations — a
@@ -1629,33 +1657,21 @@ mod tests {

    #[test]
    fn moving_cards_off_face_up_card_does_not_fire_card_flipped_event() {
-        use solitaire_core::card::{Card, Rank, Suit};
+        use solitaire_core::{Card, Deck, Rank, Suit};
        let mut app = test_app(1);
        // Build a tableau with two face-up cards.
        {
            let mut gs = app.world_mut().resource_mut::<GameStateResource>();
-            gs.0.set_test_tableau_cards(Tableau::Tableau1, vec![
-                Card {
-                    id: 910,
-                    suit: Suit::Clubs,
-                    rank: Rank::King,
-                    face_up: true,
-                },
-                Card {
-                    id: 911,
-                    suit: Suit::Hearts,
-                    rank: Rank::Queen,
-                    face_up: true,
-                },
-            ]);
+            gs.0.set_test_tableau_cards(
+                Tableau::Tableau1,
+                vec![
+                    Card::new(Deck::Deck1, Suit::Clubs, Rank::King),
+                    Card::new(Deck::Deck1, Suit::Hearts, Rank::Queen),
+                ],
+            );
            gs.0.set_test_tableau_cards(
                Tableau::Tableau2,
-                vec![Card {
-                    id: 912,
-                    suit: Suit::Spades,
-                    rank: Rank::King,
-                    face_up: true,
-                }],
+                vec![Card::new(Deck::Deck1, Suit::Spades, Rank::King)],
            );
        }

@@ -1668,7 +1684,7 @@ mod tests {

        let events = app
            .world()
-            .resource::<Messages<crate::events::CardFlippedEvent>>();
+            .resource::<Messages<CardFlippedEvent>>();
        let mut cursor = events.get_cursor();
        let fired: Vec<_> = cursor.read(events).collect();
        assert!(
@@ -1685,7 +1701,7 @@ mod tests {
    fn has_legal_moves_returns_true_for_fresh_game() {
        // A fresh deal always has a non-empty stock (24 cards), so drawing
        // is always a legal move regardless of the initial face-up tableau cards.
-        let game = GameState::new(42, DrawMode::DrawOne);
+        let game = GameState::new(42, DrawStockConfig::DrawOne);
        assert!(
            has_legal_moves(&game),
            "fresh deal must contain at least one legal move"
@@ -1698,8 +1714,8 @@ mod tests {
        // Klondike (unlimited recycles), even if the drawn card cannot be
        // immediately placed. The game is only stuck when both stock AND waste
        // are exhausted and no visible card can be moved.
-        use solitaire_core::card::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawMode::DrawOne);
+        use solitaire_core::{Card, Deck, Rank, Suit};
+        let mut game = GameState::new(1, DrawStockConfig::DrawOne);
        for foundation in [
            Foundation::Foundation1,
            Foundation::Foundation2,
@@ -1722,12 +1738,7 @@ mod tests {
        game.set_test_waste_cards(Vec::new());
        let mut stock = Vec::new();
        for r in [Rank::Two, Rank::Three, Rank::Four, Rank::Five] {
-            stock.push(Card {
-                id: 100 + r as u32,
-                suit: Suit::Hearts,
-                rank: r,
-                face_up: false,
-            });
+            stock.push(Card::new(Deck::Deck1, Suit::Hearts, r));
        }
        game.set_test_stock_cards(stock);
        // Stock is non-empty, so drawing is always a valid move.
@@ -1739,8 +1750,8 @@ mod tests {

    #[test]
    fn has_legal_moves_returns_true_when_ace_can_go_to_foundation() {
-        use solitaire_core::card::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawMode::DrawOne);
+        use solitaire_core::{Card, Deck, Rank, Suit};
+        let mut game = GameState::new(1, DrawStockConfig::DrawOne);

        // Empty stock and waste so draw is NOT available.
        game.set_test_stock_cards(Vec::new());
@@ -1768,12 +1779,7 @@ mod tests {
        }
        game.set_test_tableau_cards(
            Tableau::Tableau1,
-            vec![Card {
-                id: 1,
-                suit: Suit::Clubs,
-                rank: Rank::Ace,
-                face_up: true,
-            }],
+            vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Ace)],
        );

        assert!(
@@ -1782,14 +1788,14 @@ mod tests {
        );
    }

-        #[test]
+    #[test]
    fn has_legal_moves_detects_non_top_face_up_card_as_source() {
        // Regression: the bug only checked t.cards.last() (top face-up card).
        // If the only legal move involves a face-up card that is NOT the top
        // card of its column the previous code would return false (softlock)
        // even though the player can still move that run.
-        use solitaire_core::card::{Card, Rank, Suit};
-        let mut game = GameState::new(1, DrawMode::DrawOne);
+        use solitaire_core::{Card, Deck, Rank, Suit};
+        let mut game = GameState::new(1, DrawStockConfig::DrawOne);

        game.set_test_stock_cards(Vec::new());
        game.set_test_waste_cards(Vec::new());
@@ -1819,28 +1825,13 @@ mod tests {
        game.set_test_tableau_cards(
            Tableau::Tableau1,
            vec![
-                Card {
-                    id: 10,
-                    suit: Suit::Spades,
-                    rank: Rank::Queen,
-                    face_up: true,
-                },
-                Card {
-                    id: 11,
-                    suit: Suit::Hearts,
-                    rank: Rank::Jack,
-                    face_up: true,
-                },
+                Card::new(Deck::Deck1, Suit::Spades, Rank::Queen),
+                Card::new(Deck::Deck1, Suit::Hearts, Rank::Jack),
            ],
        );
        game.set_test_tableau_cards(
            Tableau::Tableau2,
-            vec![Card {
-                id: 12,
-                suit: Suit::Diamonds,
-                rank: Rank::King,
-                face_up: true,
-            }],
+            vec![Card::new(Deck::Deck1, Suit::Diamonds, Rank::King)],
        );

        assert!(
@@ -1868,7 +1859,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .move_count = 5;
+            .set_test_move_count(5);
        app.world_mut().write_message(NewGameRequestEvent {
            seed: None,
            mode: None,
@@ -1892,7 +1883,7 @@ mod tests {
        let mut app = test_app_with_input(42);
        // move_count stays at 0 (fresh game).
        assert_eq!(
-            app.world().resource::<GameStateResource>().0.move_count,
+            app.world().resource::<GameStateResource>().0.move_count(),
            0,
            "test assumes a fresh game with no moves"
        );
@@ -1936,16 +1927,16 @@ mod tests {
        );
    }

-        /// Verify that the game-over overlay contains the expected header text and
-    /// action-hint strings so players understand why the overlay appeared and
-    /// what keys to press.
-        // -----------------------------------------------------------------------
+    // Verify that the game-over overlay contains the expected header text and
+    // action-hint strings so players understand why the overlay appeared and
+    // what keys to press.
+    // -----------------------------------------------------------------------
    // Task #56 — Escape dismisses GameOverScreen and starts new game
    // -----------------------------------------------------------------------

-    /// Pressing Escape while `GameOverScreen` is visible must fire
-    /// `NewGameRequestEvent` — identical behaviour to pressing N.
-        // -----------------------------------------------------------------------
+    // Pressing Escape while `GameOverScreen` is visible must fire
+    // `NewGameRequestEvent` — identical behaviour to pressing N.
+    // -----------------------------------------------------------------------
    // Task #48 — Undo with empty stack fires InfoToastEvent
    // -----------------------------------------------------------------------

@@ -1988,12 +1979,12 @@ mod tests {
    /// When a King lands on a foundation that already holds Ace through
    /// Queen, exactly one `FoundationCompletedEvent` must fire and carry
    /// the matching slot + suit.
-        /// Moving a card to a tableau pile must never produce a
+    /// Moving a card to a tableau pile must never produce a
    /// `FoundationCompletedEvent`, even if the source tableau happened
    /// to have been a King.
    #[test]
    fn foundation_completed_event_does_not_fire_for_non_foundation_moves() {
-        use solitaire_core::card::{Card, Rank, Suit};
+        use solitaire_core::{Card, Deck, Rank, Suit};

        let mut app = test_app(1);
        // Reset the world: clear stock + waste so a draw isn't possible,
@@ -2025,12 +2016,7 @@ mod tests {
            }
            gs.0.set_test_tableau_cards(
                Tableau::Tableau1,
-                vec![Card {
-                    id: 7_000,
-                    suit: Suit::Spades,
-                    rank: Rank::King,
-                    face_up: true,
-                }],
+                vec![Card::new(Deck::Deck1, Suit::Spades, Rank::King)],
            );
        }

@@ -2051,7 +2037,7 @@ mod tests {
    /// At 12 cards on a foundation (Ace–Jack on the pile, Queen in
    /// flight), the event must NOT fire — the flourish is only for the
    /// final 13th completion.
-        /// A successful undo must NOT fire an `InfoToastEvent`.
+    /// A successful undo must NOT fire an `InfoToastEvent`.
    #[test]
    fn undo_after_draw_does_not_fire_info_toast() {
        let mut app = test_app(42);
@@ -2086,7 +2072,7 @@ mod tests {
    /// Drive a fresh game through a draw + a tableau→foundation move,
    /// then assert the recording resource captured both, in order, with
    /// the correct shape.
-        /// Invalid moves must not appear in the recording — the recording is
+    /// Invalid moves must not appear in the recording — the recording is
    /// "what successfully happened", not "what was requested".
    #[test]
    fn replay_does_not_record_rejected_moves() {
@@ -2124,7 +2110,7 @@ mod tests {
            1,
            "only the draw is recorded; the undo does not erase it nor add a new entry",
        );
-        assert!(matches!(recording.moves[0], ReplayMove::StockClick));
+        assert!(matches!(recording.moves[0], KlondikeInstruction::RotateStock));
    }

    /// Starting a new game wipes the recording so the next deal begins
@@ -2176,16 +2162,16 @@ mod tests {
        let mut app = test_app(7654);
        app.insert_resource(ReplayPath(Some(path.clone())));

-        // Push two recorded moves manually so we can verify they survive
-        // the freeze/save round-trip without having to drive a real win.
+        // Push two recorded instructions manually so we can verify they
+        // survive the freeze/save round-trip without having to drive a
+        // real win. Both are `RotateStock` — the only instruction
+        // constructible without the runtime-only `klondike` pile-stack
+        // types (which the engine intentionally does not depend on); the
+        // round-trip shape is identical for any instruction variant.
        {
            let mut recording = app.world_mut().resource_mut::<RecordingReplay>();
-            recording.moves.push(ReplayMove::StockClick);
-            recording.moves.push(ReplayMove::Move {
-                from: SavedKlondikePile::Stock,
-                to: SavedKlondikePile::Tableau(SavedTableau(2)),
-                count: 1,
-            });
+            recording.moves.push(KlondikeInstruction::RotateStock);
+            recording.moves.push(KlondikeInstruction::RotateStock);
        }

        // Fire the win event the engine emits when the last foundation
@@ -2207,7 +2193,7 @@ mod tests {
        assert_eq!(loaded.seed, 7654, "seed must match the live game state");
        assert_eq!(
            loaded.draw_mode,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            "draw_mode must be captured"
        );
        assert_eq!(
@@ -2219,15 +2205,8 @@ mod tests {
            "time_seconds must come from the win event"
        );
        assert_eq!(loaded.moves.len(), 2, "every recorded move must round-trip");
-        assert!(matches!(loaded.moves[0], ReplayMove::StockClick));
-        match &loaded.moves[1] {
-            ReplayMove::Move { from, to, count } => {
-                assert_eq!(*from, SavedKlondikePile::Stock);
-                assert_eq!(*to, SavedKlondikePile::Tableau(SavedTableau(2)));
-                assert_eq!(*count, 1);
-            }
-            other => panic!("second entry must be a Move, got {other:?}"),
-        }
+        assert!(matches!(loaded.moves[0], KlondikeInstruction::RotateStock));
+        assert!(matches!(loaded.moves[1], KlondikeInstruction::RotateStock));

        #[cfg(not(target_arch = "wasm32"))]
        let _ = std::fs::remove_file(&path);
@@ -2251,7 +2230,7 @@ mod tests {
        {
            let mut recording = app.world_mut().resource_mut::<RecordingReplay>();
            recording.moves.clear();
-            recording.moves.push(ReplayMove::StockClick);
+            recording.moves.push(KlondikeInstruction::RotateStock);
        }
        app.world_mut().write_message(GameWonEvent {
            score: 100,
@@ -2263,8 +2242,8 @@ mod tests {
        {
            let mut recording = app.world_mut().resource_mut::<RecordingReplay>();
            recording.moves.clear();
-            recording.moves.push(ReplayMove::StockClick);
-            recording.moves.push(ReplayMove::StockClick);
+            recording.moves.push(KlondikeInstruction::RotateStock);
+            recording.moves.push(KlondikeInstruction::RotateStock);
        }
        app.world_mut().write_message(GameWonEvent {
            score: 200,
@@ -2348,7 +2327,7 @@ mod tests {
            "with solver toggle off, the requested seed must be honoured exactly"
        );
        // Cross-check: the dealt tableau must match GameState::new(999) byte-for-byte.
-        let expected = GameState::new(999, DrawMode::DrawOne);
+        let expected = GameState::new(999, DrawStockConfig::DrawOne);
        for tableau in [
            Tableau::Tableau1,
            Tableau::Tableau2,
@@ -2359,7 +2338,10 @@ mod tests {
            Tableau::Tableau7,
        ] {
            assert_eq!(
-                app.world().resource::<GameStateResource>().0.pile(KlondikePile::Tableau(tableau)),
+                app.world()
+                    .resource::<GameStateResource>()
+                    .0
+                    .pile(KlondikePile::Tableau(tableau)),
                expected.pile(KlondikePile::Tableau(tableau)),
                "tableau column {tableau:?} must match the unfiltered seed",
            );
@@ -2387,7 +2369,7 @@ mod tests {
        app.update();

        // Game state was reseeded — move_count is 0 on the new game.
-        assert_eq!(app.world().resource::<GameStateResource>().0.move_count, 0);
+        assert_eq!(app.world().resource::<GameStateResource>().0.move_count(), 0);
    }

    #[test]
@@ -2422,7 +2404,7 @@ mod tests {
        //
        // Seed 394 was previously Unwinnable under the old DFS; now it resolves
        // as Inconclusive, so the helper must accept it immediately.
-        let chosen = choose_winnable_seed(394, DrawMode::DrawOne);
+        let chosen = choose_winnable_seed(394, DrawStockConfig::DrawOne);
        assert_eq!(
            chosen, 394,
            "seed 394 resolves as Inconclusive; choose_winnable_seed must accept it as-is"
@@ -2461,7 +2443,7 @@ mod tests {
        // The chosen seed is non-deterministic (system time),
        // but the new game must have been started cleanly:
        // move_count back to 0, undo stack empty.
-        assert_eq!(app.world().resource::<GameStateResource>().0.move_count, 0);
+        assert_eq!(app.world().resource::<GameStateResource>().0.move_count(), 0);
        assert_eq!(
            app.world()
                .resource::<GameStateResource>()
@@ -2521,7 +2503,7 @@ mod tests {
        );
        // New game completed: a fresh deal carries 0 moves.
        assert_eq!(
-            app.world().resource::<GameStateResource>().0.move_count,
+            app.world().resource::<GameStateResource>().0.move_count(),
            0,
            "completed new game must be in fresh-deal state",
        );
@@ -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();
@@ -8,9 +8,9 @@

 use bevy::prelude::*;
 use bevy::window::WindowResized;
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::card::Suit;
-use solitaire_core::game_state::{DrawMode, GameMode};
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::Suit;
+use solitaire_core::{DrawStockConfig, game_state::GameMode};

 use crate::auto_complete_plugin::AutoCompleteState;
 #[cfg(not(target_arch = "wasm32"))]
@@ -36,7 +36,6 @@ use crate::game_plugin::GameMutation;
 use crate::input_plugin::TouchDragSet;
 use crate::layout::HUD_BAND_HEIGHT;
 use crate::layout::LayoutSystem;
-#[cfg(target_os = "android")]
 use crate::pause_plugin::PausedResource;
 use crate::platform::{SHOW_KEYBOARD_ACCELERATORS, USE_TOUCH_UI_LAYOUT};
 use crate::progress_plugin::ProgressResource;
@@ -174,7 +173,7 @@ pub enum HudVisibility {
 #[cfg(target_os = "android")]
 #[derive(Resource, Debug, Default)]
 struct HudTapTracker {
-    start_pos: Option<bevy::math::Vec2>,
+    start_pos: Option<Vec2>,
    /// Set `true` when the finger-down hit an action button so the
    /// finger-up never toggles bar visibility.
    started_on_button: bool,
@@ -315,17 +314,17 @@ pub struct HintButton;
 /// Android HUD label for the Hint button — shared with the help screen's
 /// controls reference so both always agree.
 #[cfg(target_os = "android")]
-pub(crate) const ANDROID_HINT_LABEL: &str = "!";
+pub(crate) const ANDROID_HINT_LABEL: &str = "Hint";

 #[cfg(target_os = "android")]
 const ACTION_BAR_LABELS: [&str; 7] = [
-    "\u{2261}",
-    "\u{2190}",
-    "||",
-    "?",
+    "Menu",
+    "Undo",
+    "Pause",
+    "Help",
    ANDROID_HINT_LABEL,
-    "M",
-    "+",
+    "Mode",
+    "New",
 ];
 #[cfg(not(target_os = "android"))]
 const ACTION_BAR_LABELS: [&str; 7] = [
@@ -529,7 +528,7 @@ impl Plugin for HudPlugin {
        #[cfg(target_os = "android")]
        {
            app.init_resource::<HudTapTracker>()
-                .add_message::<bevy::input::touch::TouchInput>()
+                .add_message::<TouchInput>()
                .add_systems(
                    Update,
                    toggle_hud_on_tap
@@ -830,6 +829,8 @@ fn spawn_avatar_child(
 ) {
    const SIZE: f32 = 32.0;
    if let Some(handle) = avatar.and_then(|a| a.0.clone()) {
+        // Logged-in with a downloaded avatar: keep the accent disc behind it.
+        commands.entity(parent).insert(BackgroundColor(ACCENT_PRIMARY));
        // Image fills the circle container; border_radius clips it to a disc.
        commands.entity(parent).with_children(|b| {
            b.spawn((
@@ -850,6 +851,15 @@ fn spawn_avatar_child(
            })
            .and_then(|c| c.to_uppercase().next())
            .unwrap_or('?');
+        // Real initial (logged in) keeps the red accent disc; the '?'
+        // unauthenticated fallback uses a neutral grey so it reads as a
+        // "tap to log in" affordance rather than an error.
+        let disc_bg = if initial == '?' {
+            BG_ELEVATED_HI
+        } else {
+            ACCENT_PRIMARY
+        };
+        commands.entity(parent).insert(BackgroundColor(disc_bg));
        commands.entity(parent).with_children(|b| {
            b.spawn((
                Text::new(initial.to_string()),
@@ -1129,7 +1139,7 @@ fn handle_help_button(

 fn handle_hint_button(
    interaction_query: Query<&Interaction, (With<HintButton>, Changed<Interaction>)>,
-    paused: Option<Res<crate::PausedResource>>,
+    paused: Option<Res<PausedResource>>,
    game: Option<Res<GameStateResource>>,
    solver_config: Option<Res<crate::input_plugin::HintSolverConfig>>,
    mut pending_hint: Option<ResMut<crate::pending_hint::PendingHintTask>>,
@@ -1143,12 +1153,12 @@ fn handle_hint_button(
            return;
        }
        let Some(ref g) = game else { return };
-        if g.0.is_won {
+        if g.0.is_won() {
            info_toast.write(InfoToastEvent(HINT_WON_MSG.to_string()));
            return;
        }
        if let (Some(cfg), Some(hint)) = (solver_config.as_ref(), pending_hint.as_mut()) {
-            hint.spawn(g.0.clone(), cfg.0);
+            hint.spawn(g.0.clone(), cfg.moves_budget, cfg.states_budget);
        }
    }
 }
@@ -1651,11 +1661,13 @@ impl Default for HudActionFade {
 /// How many pixels from the bottom edge the cursor must be to reveal the bar.
 /// Set slightly taller than `HUD_BAND_HEIGHT` so the bar fades in as the
 /// cursor approaches, not only when it crosses into the band itself.
+#[cfg(not(target_os = "android"))]
 const ACTION_FADE_REVEAL_PX: f32 = HUD_BAND_HEIGHT + 32.0;

 /// Lerp rate for fading (per second). 6.0 ≈ 167 ms for a full
 /// transition — fast enough to feel responsive without flashing on
 /// brief cursor wanders into the reveal zone.
+#[cfg(not(target_os = "android"))]
 const ACTION_FADE_RATE_PER_SEC: f32 = 6.0;

 /// Updates the fade state from cursor position. Sets `target = 1.0` if
@@ -1663,6 +1675,7 @@ const ACTION_FADE_RATE_PER_SEC: f32 = 6.0;
 /// (player is using keyboard); `0.0` otherwise. Lerps `alpha` toward
 /// `target` at a fixed rate so the visual transition is smooth across
 /// variable framerates.
+#[cfg(not(target_os = "android"))]
 fn update_action_fade(windows: Query<&Window>, time: Res<Time>, mut fade: ResMut<HudActionFade>) {
    let Ok(window) = windows.single() else {
        return;
@@ -1687,6 +1700,7 @@ fn update_action_fade(windows: Query<&Window>, time: Res<Time>, mut fade: ResMut
 /// `Last` (after `paint_action_buttons`) so a hover-state change in the
 /// same frame doesn't override the fade with an opaque idle / hover
 /// colour.
+#[cfg(not(target_os = "android"))]
 #[allow(clippy::type_complexity)]
 fn apply_action_fade(
    fade: Res<HudActionFade>,
@@ -1803,7 +1817,7 @@ fn detect_score_change(
    score_q: Query<Entity, With<HudScore>>,
    mut commands: Commands,
 ) {
-    let current = game.0.score;
+    let current = game.0.score();
    let delta = current - prev.0;
    prev.0 = current;
    if delta <= 0 {
@@ -2091,10 +2105,10 @@ fn update_won_previously(
    let Ok(mut text) = q.single_mut() else {
        return;
    };
-    let won_before = !game.0.is_won
+    let won_before = !game.0.is_won()
        && history.as_ref().is_some_and(|h| {
            h.0.replays.iter().any(|r| {
-                r.seed == game.0.seed && r.draw_mode == game.0.draw_mode && r.mode == game.0.mode
+                r.seed == game.0.seed && r.draw_mode == game.0.draw_mode() && r.mode == game.0.mode
            })
        });
    let next = if won_before {
@@ -2260,17 +2274,17 @@ fn update_hud(
            **t = if is_zen {
                String::new()
            } else {
-                format!("Score: {}", g.score)
+                format!("Score: {}", g.score())
            };
        }
        if let Ok(mut t) = moves_q.single_mut() {
-            **t = format!("Moves: {}", g.move_count);
+            **t = format!("Moves: {}", g.move_count());
        }
        if let Ok(mut t) = mode_q.single_mut() {
            **t = match g.mode {
-                GameMode::Classic => match g.draw_mode {
-                    DrawMode::DrawOne => String::new(),
-                    DrawMode::DrawThree => "Draw 3".to_string(),
+                GameMode::Classic => match g.draw_mode() {
+                    DrawStockConfig::DrawOne => String::new(),
+                    DrawStockConfig::DrawThree => "Draw 3".to_string(),
                },
                GameMode::Zen => "ZEN".to_string(),
                GameMode::Challenge => "CHALLENGE".to_string(),
@@ -2281,7 +2295,7 @@ fn update_hud(

        // --- Daily challenge constraint (with time-low colour warning) ---
        if let Ok((mut t, mut color)) = challenge_q.single_mut() {
-            if g.is_won {
+            if g.is_won() {
                **t = String::new();
            } else if let Some(dc) = daily.as_deref() {
                **t = challenge_hud_text(dc);
@@ -2296,7 +2310,7 @@ fn update_hud(

        // --- Undo count ---
        if let Ok((mut t, mut color)) = undos_q.single_mut() {
-            let count = g.undo_count;
+            let count = g.undo_count();
            if count == 0 {
                **t = String::new();
                *color = TextColor(TEXT_PRIMARY);
@@ -2310,8 +2324,8 @@ fn update_hud(

        // --- Recycle counter (both modes, hidden until first recycle) ---
        if let Ok(mut t) = recycles_q.single_mut() {
-            **t = if g.recycle_count > 0 {
-                format!("Recycles: {}", g.recycle_count)
+            **t = if g.recycle_count() > 0 {
+                format!("Recycles: {}", g.recycle_count())
            } else {
                String::new()
            };
@@ -2319,7 +2333,7 @@ fn update_hud(

        // --- Draw-cycle indicator (Draw-Three mode only) ---
        if let Ok(mut t) = draw_cycle_q.single_mut() {
-            **t = if g.is_won || g.draw_mode != DrawMode::DrawThree {
+            **t = if g.is_won() || g.draw_mode() != DrawStockConfig::DrawThree {
                // Hide when not in Draw-Three or after the game is won.
                String::new()
            } else {
@@ -2404,11 +2418,14 @@ fn update_selection_hud(
 /// When the slot has a claimed suit (any card has landed) the announcement is
 /// "▶ {Suit} Foundation"; while the slot is empty it falls back to a
 /// "▶ Foundation N" placeholder labelled by the 1-based slot index.
-fn foundation_selection_label(slot: Foundation, game: &solitaire_core::game_state::GameState) -> String {
+fn foundation_selection_label(
+    slot: Foundation,
+    game: &solitaire_core::game_state::GameState,
+) -> String {
    let claimed = game
        .pile(KlondikePile::Foundation(slot))
        .first()
-        .map(|c| c.suit);
+        .map(|c| c.0.suit());
    match claimed {
        Some(suit) => {
            let s = match suit {
@@ -2564,10 +2581,18 @@ fn restore_hud_on_modal(
 /// Returns the action-bar label font size for a given logical window width.
 fn action_bar_font_size(window_width: f32) -> f32 {
    if USE_TOUCH_UI_LAYOUT {
-        // ~1/40 of the window width gives ~22 px on a 900 logical-px phone.
-        // Clamped so it never goes too tiny on narrow viewports or too large
-        // on landscape tablets.
-        (window_width / 40.0).clamp(16.0, 30.0)
+        // Seven word-labels ("Menu","Undo","Pause","Help","Hint","Mode","New")
+        // must share one row. The widest characters are in FiraMono (a
+        // monospace whose advance is ~0.62 of the font size). On a 900
+        // logical-px phone the row budget after bar padding (2*12) and six
+        // 4 px column gaps is ~852 px for ~28 label chars + 7*2*3 px button
+        // padding. Solving 28*0.62*size + 42 <= 852 gives size <= ~46, so the
+        // labels are advance-bound only on very narrow viewports; the real
+        // constraint is legibility, not fit. ~1/60 of the width yields ~15 px
+        // at 900 px — comfortably one row with margin to spare — clamped so it
+        // never drops below the 12 px legibility floor or grows past 18 px on
+        // landscape tablets where it would crowd the row again.
+        (window_width / 60.0).clamp(12.0, 18.0)
    } else {
        TYPE_BODY
    }
@@ -2575,9 +2600,14 @@ fn action_bar_font_size(window_width: f32) -> f32 {

 fn action_button_metrics() -> (UiRect, Val, Val) {
    if USE_TOUCH_UI_LAYOUT {
+        // Tight 3 px horizontal padding (down from 4) trims 14 px off the row
+        // total across 7 buttons, and a 44 px min_width (down from 52) lets the
+        // shortest labels ("New", "Help") shrink to their text rather than
+        // padding the row out past the 900 logical-px viewport. min_height
+        // stays at 44 px to preserve the comfortable touch target.
        (
-            UiRect::axes(Val::Px(4.0), Val::Px(4.0)),
-            Val::Px(52.0),
+            UiRect::axes(Val::Px(3.0), Val::Px(4.0)),
+            Val::Px(44.0),
            Val::Px(44.0),
        )
    } else {
@@ -2627,8 +2657,9 @@ fn resize_action_bar_labels(
 }

 #[cfg(target_os = "android")]
+#[allow(clippy::too_many_arguments)]
 fn toggle_hud_on_tap(
-    mut touch_events: MessageReader<bevy::input::touch::TouchInput>,
+    mut touch_events: MessageReader<TouchInput>,
    drag: Res<DragState>,
    scrims: Query<(), With<ModalScrim>>,
    paused: Option<Res<PausedResource>>,
@@ -2666,13 +2697,14 @@ fn toggle_hud_on_tap(
                // regardless of whether we toggle.
                let on_button = tracker.started_on_button || game_consumed.0;
                game_consumed.0 = false;
-                if let Some(start) = tracker.start_pos.take() {
-                    if !on_button && (event.position - start).length() < HUD_TAP_SLOP_PX {
-                        *hud_vis = match *hud_vis {
-                            HudVisibility::Visible => HudVisibility::Hidden,
-                            HudVisibility::Hidden => HudVisibility::Visible,
-                        };
-                    }
+                if let Some(start) = tracker.start_pos.take()
+                    && !on_button
+                    && (event.position - start).length() < HUD_TAP_SLOP_PX
+                {
+                    *hud_vis = match *hud_vis {
+                        HudVisibility::Visible => HudVisibility::Hidden,
+                        HudVisibility::Hidden => HudVisibility::Visible,
+                    };
                }
                tracker.started_on_button = false;
            }
@@ -2695,7 +2727,7 @@ mod tests {
    use crate::game_plugin::GamePlugin;
    use crate::table_plugin::TablePlugin;
    use chrono::Local;
-    use solitaire_core::game_state::{DrawMode, GameState};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    fn headless_app() -> App {
        let mut app = App::new();
@@ -2716,7 +2748,7 @@ mod tests {
    fn update_hud_runs_after_game_mutation_without_panic() {
        let mut app = headless_app();
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(42, DrawMode::DrawOne);
+            GameState::new(42, DrawStockConfig::DrawOne);
        app.update();
    }

@@ -2732,9 +2764,9 @@ mod tests {
    #[test]
    fn score_reflects_game_state() {
        let mut app = headless_app();
-        app.world_mut().resource_mut::<GameStateResource>().0.score = 750;
+        let score = app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(20);
        app.update();
-        assert_eq!(read_hud_text::<HudScore>(&mut app), "Score: 750");
+        assert_eq!(read_hud_text::<HudScore>(&mut app), format!("Score: {score}"));
    }

    #[test]
@@ -2743,7 +2775,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .move_count = 42;
+            .set_test_move_count(42);
        app.update();
        assert_eq!(read_hud_text::<HudMoves>(&mut app), "Moves: 42");
    }
@@ -2753,7 +2785,7 @@ mod tests {
        use solitaire_core::game_state::GameMode;
        let mut app = headless_app();
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new_with_mode(42, DrawMode::DrawThree, GameMode::Classic);
+            GameState::new_with_mode(42, DrawStockConfig::DrawThree, GameMode::Classic);
        app.update();
        assert_eq!(read_hud_text::<HudMode>(&mut app), "Draw 3");
    }
@@ -2763,8 +2795,7 @@ mod tests {
        use solitaire_core::game_state::GameMode;
        let mut app = headless_app();
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new_with_mode(42, DrawMode::DrawOne, GameMode::Zen);
-        app.world_mut().resource_mut::<GameStateResource>().0.score = 999;
+            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), "");
@@ -2885,7 +2916,7 @@ mod tests {
    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>().0.score = 1; // force change
+        app.world_mut().resource_mut::<GameStateResource>().set_changed();
        app.update();
        assert_eq!(read_hud_text::<HudChallenge>(&mut app), "");
    }
@@ -2900,7 +2931,7 @@ mod tests {
            target_score: None,
            max_time_secs: Some(300),
        });
-        app.world_mut().resource_mut::<GameStateResource>().0.score = 1; // force change
+        app.world_mut().resource_mut::<GameStateResource>().set_changed();
        app.update();
        assert_eq!(read_hud_text::<HudChallenge>(&mut app), "Limit: 5:00");
    }
@@ -2915,7 +2946,7 @@ mod tests {
            target_score: Some(4000),
            max_time_secs: None,
        });
-        app.world_mut().resource_mut::<GameStateResource>().0.score = 1;
+        app.world_mut().resource_mut::<GameStateResource>().set_changed();
        app.update();
        assert_eq!(read_hud_text::<HudChallenge>(&mut app), "Goal: 4000 pts");
    }
@@ -2931,7 +2962,7 @@ mod tests {
            max_time_secs: Some(300),
        });
        // Mark the game as won — HudChallenge should be empty.
-        app.world_mut().resource_mut::<GameStateResource>().0.is_won = true;
+        app.world_mut().resource_mut::<GameStateResource>().0.set_test_won(true);
        app.update();
        assert_eq!(read_hud_text::<HudChallenge>(&mut app), "");
    }
@@ -2953,7 +2984,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .undo_count = 3;
+            .force_test_undos(3);
        app.update();
        assert_eq!(read_hud_text::<HudUndos>(&mut app), "Undos: 3");
    }
@@ -2981,7 +3012,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .move_count += 1;
+            .set_test_move_count(1);
        app.update();
        assert_eq!(read_hud_text::<HudAutoComplete>(&mut app), "AUTO");
    }
@@ -2993,7 +3024,7 @@ mod tests {
        app.world_mut()
            .resource_mut::<GameStateResource>()
            .0
-            .move_count += 1;
+            .set_test_move_count(1);
        app.update();
        assert_eq!(read_hud_text::<HudAutoComplete>(&mut app), "");
    }
@@ -3007,7 +3038,7 @@ mod tests {
        let mut app = headless_app();
        // Draw-One, no recycles yet — text must be empty.
        app.world_mut().resource_mut::<GameStateResource>().0 =
-            GameState::new(42, DrawMode::DrawOne);
+            GameState::new(42, DrawStockConfig::DrawOne);
        app.update();
        assert_eq!(read_hud_text::<HudRecycles>(&mut app), "");
    }
@@ -3017,7 +3048,7 @@ mod tests {
        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, DrawMode::DrawThree);
+            GameState::new(42, DrawStockConfig::DrawThree);
        app.update();
        assert_eq!(read_hud_text::<HudRecycles>(&mut app), "");
    }
@@ -3025,8 +3056,8 @@ mod tests {
    #[test]
    fn recycles_hud_shows_count_draw_three() {
        let mut app = headless_app();
-        let mut gs = GameState::new(42, DrawMode::DrawThree);
-        gs.recycle_count = 3;
+        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");
@@ -3036,8 +3067,8 @@ mod tests {
    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, DrawMode::DrawOne);
-        gs.recycle_count = 2;
+        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");
@@ -3077,7 +3108,7 @@ mod tests {
        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.score = 50;
+        app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
        app.update();

        // One floater should now exist.
@@ -3098,7 +3129,7 @@ mod tests {
    #[test]
    fn score_floater_despawns_after_full_lifetime() {
        let mut app = headless_app();
-        app.world_mut().resource_mut::<GameStateResource>().0.score = 100;
+        app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
        app.update();
        assert_eq!(count_with::<ScoreFloater>(&mut app), 1);

@@ -3124,7 +3155,7 @@ mod tests {
        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.score = 5;
+        app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(5);
        app.update();
        assert_eq!(
            count_with::<ScoreFloater>(&mut app),
@@ -3200,7 +3231,7 @@ mod tests {
            ..Settings::default()
        }));
        // +100 would normally create both a ScorePulse and a ScoreFloater.
-        app.world_mut().resource_mut::<GameStateResource>().0.score = 100;
+        app.world_mut().resource_mut::<GameStateResource>().0.force_test_score(50);
        app.update();
        assert_eq!(
            count_with::<ScorePulse>(&mut app),
@@ -7,7 +7,7 @@ use std::collections::HashMap;

 use bevy::math::Vec2;
 use bevy::prelude::{Resource, SystemSet};
-use klondike::{Foundation, KlondikePile, Tableau};
+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
@@ -269,7 +269,10 @@ pub fn compute_layout(
            5 => Tableau::Tableau6,
            _ => Tableau::Tableau7,
        };
-        pile_positions.insert(KlondikePile::Tableau(tableau), Vec2::new(col_x(i), tableau_y));
+        pile_positions.insert(
+            KlondikePile::Tableau(tableau),
+            Vec2::new(col_x(i), tableau_y),
+        );
    }

    // Adaptive tableau fan fraction. On height-limited (desktop) windows the
@@ -339,7 +342,9 @@ mod tests {
            Tableau::Tableau7,
        ] {
            assert!(
-                layout.pile_positions.contains_key(&KlondikePile::Tableau(tableau)),
+                layout
+                    .pile_positions
+                    .contains_key(&KlondikePile::Tableau(tableau)),
                "missing tableau {tableau:?}"
            );
        }
@@ -740,7 +745,7 @@ mod tests {
        );
        // 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| {
+        let card_top = |layout: &Layout| {
            layout.pile_positions[&KlondikePile::Stock].y + layout.card_size.y / 2.0
        };
        assert!(
@@ -758,7 +763,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 [KlondikePile::Stock, KlondikePile::Tableau(Tableau::Tableau1), KlondikePile::Tableau(Tableau::Tableau7)] {
+        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",
@@ -862,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
@@ -1091,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
    }
@@ -153,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,
@@ -179,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 klondike::KlondikePile;
-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: KlondikePile, to: KlondikePile },
+    /// 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,9 +178,9 @@ mod tests {
    use super::*;
    use crate::events::HintVisualEvent;
    use crate::input_plugin::HintSolverConfig;
-    use klondike::{Foundation, Tableau};
-    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.
@@ -214,7 +209,7 @@ 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);
+        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 [
@@ -261,13 +256,8 @@ mod tests {
        .zip(suits.iter())
        {
            let mut cards = Vec::new();
-            for (i, rank) in ranks_below_king.iter().enumerate() {
-                cards.push(Card {
-                    id: (foundation as u32) * 13 + i as u32,
-                    suit: *suit,
-                    rank: *rank,
-                    face_up: true,
-                });
+            for rank in ranks_below_king.iter() {
+                cards.push(Card::new(Deck::Deck1, *suit, *rank));
            }
            game.set_test_foundation_cards(foundation, cards);
        }
@@ -282,12 +272,7 @@ mod tests {
        {
            game.set_test_tableau_cards(
                tableau,
-                vec![Card {
-                    id: 100 + tableau as u32,
-                    suit: *suit,
-                    rank: Rank::King,
-                    face_up: true,
-                }],
+                vec![Card::new(Deck::Deck1, *suit, Rank::King)],
            );
        }
        game
@@ -302,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() {
@@ -341,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",
@@ -377,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);

@@ -391,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;
        }
@@ -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,8 +47,8 @@ use bevy::input::touch::Touches;
 use bevy::math::Vec2;
 use bevy::prelude::*;
 use bevy::window::PrimaryWindow;
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::card::Card;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::Card;
 use solitaire_core::game_state::GameState;

 use crate::card_plugin::TABLEAU_FACEDOWN_FAN_FRAC;
@@ -113,9 +113,9 @@ pub enum RightClickRadialState {
        /// 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
@@ -304,7 +304,7 @@ pub fn find_top_face_up_card_at(
        let is_tableau = matches!(pile, KlondikePile::Tableau(_));
        for i in (0..pile_cards.len()).rev() {
            let card = &pile_cards[i];
-            if !card.face_up {
+            if !card.1 {
                continue;
            }
            // Only the top card is draggable on non-tableau piles.
@@ -320,7 +320,7 @@ pub fn find_top_face_up_card_at(
            {
                continue;
            }
-            return Some((pile, card.clone()));
+            return Some((pile, card.0.clone()));
        }
    }
    None
@@ -329,12 +329,17 @@ 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: &KlondikePile, 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, KlondikePile::Tableau(_)) {
        let mut y_offset = 0.0_f32;
        for card in pile_cards(game, pile).iter().take(stack_index) {
-            let step = if card.face_up {
+            let step = if card.1 {
                TABLEAU_FAN_FRAC
            } else {
                TABLEAU_FACEDOWN_FAN_FRAC
@@ -347,13 +352,14 @@ fn card_position(game: &GameState, layout: &Layout, pile: &KlondikePile, stack_i
    }
 }

-fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<Card> {
+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,
@@ -376,16 +382,27 @@ const fn tableaus() -> [Tableau; 7] {
 }

 /// Builds the `(destination, anchor)` list for a fresh radial open.
-fn build_radial_destinations(centre: Vec2, dests: Vec<KlondikePile>) -> Vec<(KlondikePile, 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()
 }
@@ -472,12 +489,17 @@ fn radial_open_on_right_click(
        });
        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,
@@ -498,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>>,
@@ -540,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,
@@ -767,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
@@ -791,7 +819,7 @@ 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.set_test_stock_cards(Vec::new());
        g.set_test_waste_cards(Vec::new());
@@ -817,12 +845,7 @@ mod tests {
        // Ace of Clubs on Tableau(0).
        g.set_test_tableau_cards(
            Tableau::Tableau1,
-            vec![CoreCard {
-                id: 100,
-                suit: Suit::Clubs,
-                rank: Rank::Ace,
-                face_up: true,
-            }],
+            vec![CoreCard::new(Deck::Deck1, Suit::Clubs, Rank::Ace)],
        );
        g
    }
@@ -830,7 +853,7 @@ mod tests {
    /// 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);
+        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 [
@@ -852,14 +875,9 @@ mod tests {
        ] {
            g.set_test_tableau_cards(tableau, Vec::new());
        }
-        g.set_test_tableau_cards(
+        g.set_test_tableau_cards_with_face(
            Tableau::Tableau1,
-            vec![CoreCard {
-                id: 100,
-                suit: Suit::Spades,
-                rank: Rank::King,
-                face_up: false,
-            }],
+            vec![(CoreCard::new(Deck::Deck1, Suit::Spades, Rank::King), false)],
        );
        g
    }
@@ -952,13 +970,9 @@ 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, &KlondikePile::Tableau(Tableau::Tableau1), &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!(
@@ -971,13 +985,12 @@ mod tests {
    #[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, &KlondikePile::Foundation(Foundation::Foundation1), &g);
+        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)));
    }

@@ -988,7 +1001,7 @@ 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.
-        /// Releasing the right button while the cursor is over a destination
+    /// Releasing the right button while the cursor is over a destination
    /// icon must fire a `MoveRequestEvent` and return the state to Idle.
    #[test]
    fn right_click_release_over_destination_fires_move_request() {
@@ -1005,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"),
        };

@@ -1,10 +1,8 @@
 use super::ReplayPlaybackState;
 use chrono::Datelike;
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::card::{Card, Rank, Suit};
 use solitaire_core::game_state::GameState;
-use solitaire_core::klondike_adapter::SavedKlondikePile;
-use solitaire_data::ReplayMove;
+use solitaire_core::{Card, Rank, Suit};
+use solitaire_core::{Foundation, KlondikeInstruction, KlondikePile, Tableau};

 /// Pure helper — formats the `GAME #YYYY-DDD` caption for the given
 /// state. Returns `None` for `Inactive` / `Completed` (the replay is
@@ -60,12 +58,6 @@ pub(crate) fn format_pile(p: &KlondikePile) -> String {
    }
 }

-pub(crate) fn format_saved_pile(p: &SavedKlondikePile) -> String {
-    KlondikePile::try_from(*p)
-        .map(|pile| format_pile(&pile))
-        .unwrap_or_else(|_| "unknown pile".to_string())
-}
-
 fn foundation_number(foundation: Foundation) -> u8 {
    match foundation {
        Foundation::Foundation1 => 1,
@@ -87,17 +79,37 @@ fn tableau_number(tableau: Tableau) -> u8 {
    }
 }

-/// Pure helper — formats a [`ReplayMove`] as the body of a
-/// move-log row. `StockClick` reads as `"stock cycle"`; `Move`
-/// reads as `"{from} → {to}"` using [`format_pile`] for both
-/// endpoints. The `count` field is omitted from the row body —
-/// at row scale it adds visual noise without meaningful
+/// Pure helper — formats a [`KlondikeInstruction`] as the body of a
+/// move-log row. `RotateStock` reads as `"stock cycle"`; a `Dst*`
+/// instruction reads as `"{from} → {to}"` using [`format_pile`] for
+/// each nameable endpoint. The card count is omitted from the row
+/// body — at row scale it adds visual noise without meaningful
 /// information for the typical 1-card moves.
-pub(crate) fn format_move_body(m: &ReplayMove) -> String {
-    match m {
-        ReplayMove::StockClick => "stock cycle".to_string(),
-        ReplayMove::Move { from, to, .. } => {
-            format!("{} \u{2192} {}", format_saved_pile(from), format_saved_pile(to))
+///
+/// The destination pile is always recoverable directly from the
+/// instruction. The source pile is shown when it is statically
+/// nameable (a `DstFoundation` carries a [`KlondikePile`] source);
+/// a `DstTableau`'s source is the runtime-only `KlondikePileStack`
+/// type — not re-exported across the `solitaire_core` boundary and so
+/// not pattern-matchable here — so its row renders `"→ {to}"` without
+/// a leading source label. Faithful full-coordinate decoding lives in
+/// [`GameState::instruction_to_piles`] on the playback path; the
+/// move-log is a display-only digest.
+pub(crate) fn format_move_body(instruction: &KlondikeInstruction) -> String {
+    match instruction {
+        KlondikeInstruction::RotateStock => "stock cycle".to_string(),
+        KlondikeInstruction::DstFoundation(dst) => {
+            format!(
+                "{} \u{2192} {}",
+                format_pile(&dst.src),
+                format_pile(&KlondikePile::Foundation(dst.foundation))
+            )
+        }
+        KlondikeInstruction::DstTableau(dst) => {
+            format!(
+                "\u{2192} {}",
+                format_pile(&KlondikePile::Tableau(dst.tableau))
+            )
        }
    }
 }
@@ -232,9 +244,9 @@ pub(crate) fn format_suit_glyph(suit: Suit) -> &'static str {

 /// Pure helper — compact 2-char card label (`rank + suit glyph`) for a
 /// known card, or `"--"` for an absent top card (empty pile).
-pub(crate) fn format_card_short(card: Option<&Card>) -> String {
+pub(crate) fn format_card_short(card: Option<&(Card, bool)>) -> String {
    match card {
-        Some(c) => format!("{}{}", format_rank_short(c.rank), format_suit_glyph(c.suit)),
+        Some((c, _)) => format!("{}{}", format_rank_short(c.rank()), format_suit_glyph(c.suit())),
        None => "--".to_string(),
    }
 }
@@ -8,6 +8,7 @@ use crate::replay_playback::{
    ReplayPlaybackState, step_backwards_replay_playback, step_replay_playback,
    stop_replay_playback, toggle_pause_replay_playback,
 };
+use crate::resources::GameStateResource;

 /// Per-arrow-key time-since-last-fire accumulators that drive the
 /// continuous-scrub repeat behaviour for held arrow keys. Each
@@ -1033,6 +1034,7 @@ pub(crate) fn handle_pause_button(
 /// guard lives inside `step_replay_playback`.
 pub(crate) fn handle_step_button(
    mut state: ResMut<ReplayPlaybackState>,
+    game: Option<Res<GameStateResource>>,
    mut moves_writer: MessageWriter<MoveRequestEvent>,
    mut draws_writer: MessageWriter<DrawRequestEvent>,
    buttons: Query<&Interaction, (With<ReplayStepButton>, Changed<Interaction>)>,
@@ -1040,7 +1042,12 @@ pub(crate) fn handle_step_button(
    if !buttons.iter().any(|i| *i == Interaction::Pressed) {
        return;
    }
-    step_replay_playback(&mut state, &mut moves_writer, &mut draws_writer);
+    step_replay_playback(
+        &mut state,
+        game.as_deref(),
+        &mut moves_writer,
+        &mut draws_writer,
+    );
 }

 /// Repaints the Pause / Resume button's label whenever
@@ -1112,6 +1119,7 @@ pub(crate) fn handle_pause_keyboard(
 pub(crate) fn handle_arrow_keyboard(
    keys: Option<Res<ButtonInput<KeyCode>>>,
    time: Res<Time>,
+    game: Option<Res<GameStateResource>>,
    mut hold: ResMut<ReplayScrubKeyHold>,
    mut state: ResMut<ReplayPlaybackState>,
    mut moves_writer: MessageWriter<MoveRequestEvent>,
@@ -1136,12 +1144,22 @@ pub(crate) fn handle_arrow_keyboard(
    // Right (forward step) — initial press fires immediately;
    // held repeats fire when the accumulator crosses the interval.
    if keys.just_pressed(KeyCode::ArrowRight) {
-        step_replay_playback(&mut state, &mut moves_writer, &mut draws_writer);
+        step_replay_playback(
+            &mut state,
+            game.as_deref(),
+            &mut moves_writer,
+            &mut draws_writer,
+        );
        hold.right_held_secs = 0.0;
    } else if keys.pressed(KeyCode::ArrowRight) {
        hold.right_held_secs += dt;
        if hold.right_held_secs >= SCRUB_REPEAT_INTERVAL_SECS {
-            step_replay_playback(&mut state, &mut moves_writer, &mut draws_writer);
+            step_replay_playback(
+                &mut state,
+                game.as_deref(),
+                &mut moves_writer,
+                &mut draws_writer,
+            );
            hold.right_held_secs = 0.0;
        }
    } else {
@@ -25,15 +25,14 @@

 mod format;
 mod input;
-mod update;
 #[cfg(test)]
 mod tests;
+mod update;

 pub(crate) use self::format::*;
 pub(crate) use self::input::*;
 pub(crate) use self::update::*;

-use bevy::prelude::*;
 use crate::events::{DrawRequestEvent, MoveRequestEvent, StateChangedEvent, UndoRequestEvent};
 use crate::font_plugin::FontResource;
 use crate::platform::SHOW_KEYBOARD_ACCELERATORS;
@@ -44,6 +43,7 @@ use crate::ui_theme::{
    STATE_SUCCESS, STATE_SUCCESS_HC, TEXT_PRIMARY, TEXT_PRIMARY_HC, TEXT_SECONDARY, TYPE_BODY,
    TYPE_CAPTION, TYPE_HEADLINE, VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_4, Z_DROP_OVERLAY,
 };
+use bevy::prelude::*;

 // ---------------------------------------------------------------------------
 // Z-index — see `ui_theme::Z_MODAL_SCRIM` (200) for the next layer above.
@@ -316,7 +316,6 @@ pub struct ReplayOverlayScrubNotch;
 #[derive(Component, Debug)]
 pub struct ReplayOverlayScrubNotchLabel;

-
 /// Marker on the keybind-hint footer row at the bottom edge of the
 /// banner. Carries two `Text` children: a vim-style mode indicator
 /// (`▌ NORMAL │ replay`) on the left and the keybind hint
@@ -1270,4 +1269,3 @@ fn win_move_marker_pct(state: &ReplayPlaybackState) -> Option<f32> {
    let frac = (idx as f32 / total as f32).clamp(0.0, 1.0);
    Some(frac * 100.0)
 }
-
@@ -1,24 +1,25 @@
 use super::*;
 use chrono::NaiveDate;
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::card::{Rank, Suit};
-use solitaire_core::game_state::{DrawMode, GameMode};
-use solitaire_core::klondike_adapter::{SavedKlondikePile, SavedTableau};
-use solitaire_data::{Replay, ReplayMove};
+use solitaire_core::{DrawStockConfig, game_state::GameMode};
+use solitaire_core::{Foundation, KlondikeInstruction, KlondikePile, Tableau};
+use solitaire_core::{Rank, Suit};
+use solitaire_data::Replay;

 /// Build a minimal but well-formed [`Replay`] with `move_count` no-op
-/// `StockClick` entries. Tests only ever read `replay.moves.len()`
+/// `RotateStock` entries. Tests only ever read `replay.moves.len()`
 /// (denominator of the progress indicator), so the move kind is
 /// irrelevant beyond producing the right count.
 fn synthetic_replay(move_count: usize) -> Replay {
    Replay::new(
        42,
-        DrawMode::DrawOne,
+        DrawStockConfig::DrawOne,
        GameMode::Classic,
        120,
        1_000,
        NaiveDate::from_ymd_opt(2026, 5, 2).expect("valid date"),
-        (0..move_count).map(|_| ReplayMove::StockClick).collect(),
+        (0..move_count)
+            .map(|_| KlondikeInstruction::RotateStock)
+            .collect(),
    )
 }

@@ -854,8 +855,7 @@ fn scrub_notch_labels_carry_helper_strings() {

    let mut texts = scrub_notch_label_texts(&mut app);
    texts.sort();
-    let mut expected: Vec<String> =
-        scrub_notch_labels().iter().map(|s| s.to_string()).collect();
+    let mut expected: Vec<String> = scrub_notch_labels().iter().map(|s| s.to_string()).collect();
    expected.sort();
    assert_eq!(
        texts, expected,
@@ -1106,26 +1106,35 @@ fn move_log_active_row_text(app: &mut App) -> String {
 #[test]
 fn format_pile_uses_one_indexed_lowercase_names() {
    assert_eq!(format_pile(&KlondikePile::Stock), "waste");
-    assert_eq!(format_pile(&KlondikePile::Foundation(Foundation::Foundation1)), "foundation 1");
-    assert_eq!(format_pile(&KlondikePile::Foundation(Foundation::Foundation3)), "foundation 3");
-    assert_eq!(format_pile(&KlondikePile::Tableau(Tableau::Tableau1)), "tableau 1");
-    assert_eq!(format_pile(&KlondikePile::Tableau(Tableau::Tableau7)), "tableau 7");
+    assert_eq!(
+        format_pile(&KlondikePile::Foundation(Foundation::Foundation1)),
+        "foundation 1"
+    );
+    assert_eq!(
+        format_pile(&KlondikePile::Foundation(Foundation::Foundation3)),
+        "foundation 3"
+    );
+    assert_eq!(
+        format_pile(&KlondikePile::Tableau(Tableau::Tableau1)),
+        "tableau 1"
+    );
+    assert_eq!(
+        format_pile(&KlondikePile::Tableau(Tableau::Tableau7)),
+        "tableau 7"
+    );
 }

-/// Move-body formatter renders `StockClick` as a label and
-/// `Move` as a `from → to` arrow. The `count` field is
-/// deliberately omitted — at row scale it adds noise.
+/// Move-body formatter renders `RotateStock` as a label. The
+/// `Dst*` variants render as a `→ to` arrow, but their pile-stack
+/// source types are runtime-only and not constructible from this
+/// crate, so only the stock-cycle label is asserted here; the
+/// arrow path is exercised end-to-end through the move-log
+/// integration tests.
 #[test]
-fn format_move_body_handles_both_variants() {
-    assert_eq!(format_move_body(&ReplayMove::StockClick), "stock cycle");
+fn format_move_body_handles_stock_cycle() {
    assert_eq!(
-        format_move_body(&ReplayMove::Move {
-            from: SavedKlondikePile::Stock,
-            to: SavedKlondikePile::Tableau(SavedTableau(4)),
-            count: 1,
-        }),
-        "waste \u{2192} tableau 5",
-        "Move variant must render as `{{from}} → {{to}}` with 1-indexed pile numbers",
+        format_move_body(&KlondikeInstruction::RotateStock),
+        "stock cycle"
    );
 }

@@ -2303,8 +2312,8 @@ fn format_suit_glyph_all_suits() {
 fn format_foundations_row_empty_board() {
    let game = solitaire_core::game_state::GameState::new_with_mode(
        42,
-        solitaire_core::game_state::DrawMode::DrawOne,
-        solitaire_core::game_state::GameMode::Classic,
+        DrawStockConfig::DrawOne,
+        GameMode::Classic,
    );
    assert_eq!(format_foundations_row(&game), "F: -- -- -- --");
 }
@@ -2315,8 +2324,8 @@ fn format_foundations_row_empty_board() {
 fn format_stock_waste_row_initial_state() {
    let game = solitaire_core::game_state::GameState::new_with_mode(
        42,
-        solitaire_core::game_state::DrawMode::DrawOne,
-        solitaire_core::game_state::GameMode::Classic,
+        DrawStockConfig::DrawOne,
+        GameMode::Classic,
    );
    let text = format_stock_waste_row(&game);
    assert!(
@@ -1,15 +1,14 @@
 use bevy::prelude::*;

-use super::*;
 use super::format::{
-    format_active_move_row, format_foundations_row, format_kth_next_row,
-    format_kth_recent_row, format_move_log_header, format_progress, format_stock_waste_row,
+    format_active_move_row, format_foundations_row, format_kth_next_row, format_kth_recent_row,
+    format_move_log_header, format_progress, format_stock_waste_row,
 };
+use super::*;
 use crate::layout::LayoutResource;
 use crate::replay_playback::ReplayPlaybackState;
 use crate::resources::GameStateResource;
-use klondike::KlondikePile;
-use solitaire_data::ReplayMove;
+use solitaire_core::{KlondikeInstruction, KlondikePile};

 /// Overwrites the banner label whenever the resource changes — covers the
 /// `Playing → Completed` transition by swapping "▌ replay" for
@@ -85,9 +84,15 @@ pub(crate) fn update_floating_progress_chip(
    // the most-recently-applied move sits at `cursor - 1`.
    let dest_pile = match state.as_ref() {
        ReplayPlaybackState::Playing { replay, cursor, .. } if *cursor > 0 => {
+            // The destination pile is recoverable directly from the
+            // instruction — no live state needed. `RotateStock` has no
+            // destination (the chip hides over the stock pile).
            match &replay.moves[cursor - 1] {
-                ReplayMove::Move { to, .. } => Some(*to),
-                ReplayMove::StockClick => None,
+                KlondikeInstruction::DstFoundation(dst) => {
+                    Some(KlondikePile::Foundation(dst.foundation))
+                }
+                KlondikeInstruction::DstTableau(dst) => Some(KlondikePile::Tableau(dst.tableau)),
+                KlondikeInstruction::RotateStock => None,
            }
        }
        _ => None,
@@ -95,8 +100,7 @@ pub(crate) fn update_floating_progress_chip(

    let Some(world_pos) = dest_pile
        .as_ref()
-        .and_then(|p| KlondikePile::try_from(*p).ok())
-        .and_then(|p| layout.0.pile_positions.get(&p).copied())
+        .and_then(|p| layout.0.pile_positions.get(p).copied())
    else {
        // Nothing to point at — hide every chip and exit.
        for (_, mut visibility, _) in chips.iter_mut() {
@@ -40,8 +40,8 @@
 //! flag is threaded through, no every-callsite gate is added.

 use bevy::prelude::*;
-use klondike::KlondikePile;
-use solitaire_data::{Replay, ReplayMove};
+use solitaire_core::KlondikeInstruction;
+use solitaire_data::Replay;

 use crate::events::{DrawRequestEvent, MoveRequestEvent, StateChangedEvent, UndoRequestEvent};
 use crate::game_plugin::{GameMutation, RecordingReplay};
@@ -94,7 +94,7 @@ pub const REPLAY_COMPLETION_LINGER_SECS: f32 = 5.0;
 ///    replay's recorded deal.
 /// 3. The tick system [`tick_replay_playback`] advances `cursor` once
 ///    per [`REPLAY_MOVE_INTERVAL_SECS`] and fires the canonical event
-///    for each [`ReplayMove`].
+///    for each [`KlondikeInstruction`].
 /// 4. When `cursor == replay.moves.len()`, the state transitions to
 ///    [`Completed`](Self::Completed). It lingers for
 ///    [`REPLAY_COMPLETION_LINGER_SECS`] (driven by
@@ -251,6 +251,7 @@ pub fn toggle_pause_replay_playback(state: &mut ResMut<ReplayPlaybackState>) ->
 /// normal advance loop takes.
 pub fn step_replay_playback(
    state: &mut ResMut<ReplayPlaybackState>,
+    game: Option<&GameStateResource>,
    moves_writer: &mut MessageWriter<MoveRequestEvent>,
    draws_writer: &mut MessageWriter<DrawRequestEvent>,
 ) -> bool {
@@ -266,30 +267,49 @@ pub fn step_replay_playback(
    if *cursor >= replay.moves.len() {
        return false;
    }
-    match &replay.moves[*cursor] {
-        ReplayMove::Move { from, to, count } => {
-            let (Ok(from), Ok(to)) = (
-                KlondikePile::try_from(*from),
-                KlondikePile::try_from(*to),
-            ) else {
-                warn!("skipping replay move with invalid pile encoding at cursor {}", *cursor);
-                *cursor += 1;
-                return false;
-            };
-            moves_writer.write(MoveRequestEvent {
-                from,
-                to,
-                count: *count,
-            });
-        }
-        ReplayMove::StockClick => {
-            draws_writer.write(DrawRequestEvent);
-        }
-    }
+    let instruction = replay.moves[*cursor];
+    dispatch_instruction(instruction, *cursor, game, moves_writer, draws_writer);
    *cursor += 1;
    true
 }

+/// Translates one recorded [`KlondikeInstruction`] into the canonical
+/// engine event that drives the live animation pipeline.
+///
+/// `RotateStock` fires a [`DrawRequestEvent`]; a `Dst*` instruction is
+/// decoded back to its runtime `(from, to, count)` pile coordinates via
+/// [`GameState::instruction_to_piles`] against the *current* live state
+/// (decoded before the event mutates it, so the source pile's face-up
+/// run length is the one in effect when the move applies) and fires a
+/// [`MoveRequestEvent`]. A decode that returns `None` (e.g. a malformed
+/// instruction loaded from disk) is skipped with a warning rather than
+/// panicking — the cursor still advances so playback never stalls.
+///
+/// `game` is `None` only in headless fixtures that install no
+/// [`GameStateResource`]; in that case only `RotateStock` (which needs
+/// no live state) is dispatched and `Dst*` instructions are skipped.
+fn dispatch_instruction(
+    instruction: KlondikeInstruction,
+    cursor: usize,
+    game: Option<&GameStateResource>,
+    moves_writer: &mut MessageWriter<MoveRequestEvent>,
+    draws_writer: &mut MessageWriter<DrawRequestEvent>,
+) {
+    match instruction {
+        KlondikeInstruction::RotateStock => {
+            draws_writer.write(DrawRequestEvent);
+        }
+        _ => match game.and_then(|g| g.0.instruction_to_piles(instruction)) {
+            Some((from, to, count)) => {
+                moves_writer.write(MoveRequestEvent { from, to, count });
+            }
+            None => {
+                warn!("skipping replay move that did not decode to piles at cursor {cursor}");
+            }
+        },
+    }
+}
+
 /// Steps the replay **backwards** by exactly one move while paused.
 ///
 /// Strategy: the live game's undo system is the source of truth for
@@ -354,6 +374,7 @@ pub fn step_backwards_replay_playback(
 fn tick_replay_playback(
    time: Res<Time>,
    settings: Option<Res<SettingsResource>>,
+    game: Option<Res<GameStateResource>>,
    mut state: ResMut<ReplayPlaybackState>,
    mut moves_writer: MessageWriter<MoveRequestEvent>,
    mut draws_writer: MessageWriter<DrawRequestEvent>,
@@ -377,28 +398,14 @@ fn tick_replay_playback(
        if !*paused {
            *secs_to_next -= dt;
            while *secs_to_next <= 0.0 && *cursor < replay.moves.len() {
-                match &replay.moves[*cursor] {
-                    ReplayMove::Move { from, to, count } => {
-                        if let (Ok(from), Ok(to)) = (
-                            KlondikePile::try_from(*from),
-                            KlondikePile::try_from(*to),
-                        ) {
-                            moves_writer.write(MoveRequestEvent {
-                                from,
-                                to,
-                                count: *count,
-                            });
-                        } else {
-                            warn!(
-                                "skipping replay move with invalid pile encoding at cursor {}",
-                                *cursor
-                            );
-                        }
-                    }
-                    ReplayMove::StockClick => {
-                        draws_writer.write(DrawRequestEvent);
-                    }
-                }
+                let instruction = replay.moves[*cursor];
+                dispatch_instruction(
+                    instruction,
+                    *cursor,
+                    game.as_deref(),
+                    &mut moves_writer,
+                    &mut draws_writer,
+                );
                *cursor += 1;
                *secs_to_next += interval;
            }
@@ -555,9 +562,8 @@ mod tests {
    use crate::game_plugin::GamePlugin;
    use bevy::time::TimeUpdateStrategy;
    use chrono::NaiveDate;
-    use klondike::{KlondikePile, Tableau};
-    use solitaire_core::game_state::{DrawMode, GameMode};
-    use solitaire_core::klondike_adapter::{SavedKlondikePile, SavedTableau};
+    use solitaire_core::KlondikeInstruction;
+    use solitaire_core::{DrawStockConfig, game_state::GameMode};
    use std::time::Duration;

    /// Builds a headless `App` with `MinimalPlugins`, `GamePlugin`, and
@@ -592,25 +598,24 @@ mod tests {
        }
    }

-    /// A 3-move replay covering both `Move` and `StockClick` variants.
-    /// Seed 12345 is arbitrary — the test asserts on event counts and
-    /// move shapes, not on board positions.
+    /// A 3-move replay of `RotateStock` inputs. Pile-position types are
+    /// runtime-only and intentionally not constructible from the engine
+    /// crate, so a `Dst*` fixture can't be hand-built here; `RotateStock`
+    /// exercises the dispatch path (it fires a `DrawRequestEvent` without
+    /// needing a live state to decode piles). Seed 12345 is arbitrary —
+    /// the test asserts on event counts, not board positions.
    fn sample_replay_three_moves() -> Replay {
        Replay::new(
            12345,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            GameMode::Classic,
            60,
            500,
            NaiveDate::from_ymd_opt(2026, 5, 5).expect("valid date"),
            vec![
-                ReplayMove::StockClick,
-                ReplayMove::Move {
-                    from: SavedKlondikePile::Stock,
-                    to: SavedKlondikePile::Tableau(SavedTableau(3)),
-                    count: 1,
-                },
-                ReplayMove::StockClick,
+                KlondikeInstruction::RotateStock,
+                KlondikeInstruction::RotateStock,
+                KlondikeInstruction::RotateStock,
            ],
        )
    }
@@ -748,20 +753,17 @@ mod tests {
        let captured_moves = app.world().resource::<CapturedMoves>();
        let captured_draws = app.world().resource::<CapturedDraws>();

-        // Sample replay: StockClick, Move { Waste -> Tableau(3), 1 }, StockClick.
+        // Sample replay: three `RotateStock` inputs — each dispatches a
+        // `DrawRequestEvent` and never a `MoveRequestEvent`.
        assert_eq!(
-            captured_draws.0, 2,
-            "expected 2 DrawRequestEvent (two StockClicks)",
+            captured_draws.0, 3,
+            "expected 3 DrawRequestEvent (one per RotateStock)",
        );
        assert_eq!(
            captured_moves.0.len(),
-            1,
-            "expected 1 MoveRequestEvent (the single Move variant)",
+            0,
+            "RotateStock inputs must not produce MoveRequestEvent",
        );
-        let m = &captured_moves.0[0];
-        assert!(matches!(m.from, KlondikePile::Stock));
-        assert!(matches!(m.to, KlondikePile::Tableau(Tableau::Tableau4)));
-        assert_eq!(m.count, 1);
    }

    /// Driving past one interval on a single-move replay must
@@ -771,12 +773,12 @@ mod tests {
        let mut app = headless_app();
        let one_move = Replay::new(
            42,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            GameMode::Classic,
            10,
            100,
            NaiveDate::from_ymd_opt(2026, 5, 5).expect("valid date"),
-            vec![ReplayMove::StockClick],
+            vec![KlondikeInstruction::RotateStock],
        );
        start_playback(&mut app, one_move);
        app.update();
@@ -822,7 +824,7 @@ mod tests {
        // Replay — their in-flight recording must not get clobbered.
        {
            let mut rec = app.world_mut().resource_mut::<RecordingReplay>();
-            rec.moves.push(ReplayMove::StockClick);
+            rec.moves.push(KlondikeInstruction::RotateStock);
        }
        start_playback(&mut app, sample_replay_three_moves());
        app.update();
@@ -880,12 +882,12 @@ mod tests {
        fn ten_draws_replay() -> Replay {
            Replay::new(
                7,
-                DrawMode::DrawOne,
+                DrawStockConfig::DrawOne,
                GameMode::Classic,
                10,
                100,
                NaiveDate::from_ymd_opt(2026, 5, 5).expect("valid date"),
-                vec![ReplayMove::StockClick; 10],
+                vec![KlondikeInstruction::RotateStock; 10],
            )
        }

@@ -6,8 +6,9 @@ use std::sync::Arc;
 use bevy::math::Vec2;
 use bevy::prelude::Resource;
 use chrono::{DateTime, Utc};
+use solitaire_core::KlondikePile;
+use solitaire_core::Card;
 use solitaire_core::game_state::GameState;
-use klondike::KlondikePile;

 /// Wraps the currently active `GameState`. Single source of truth for the in-progress game.
 #[derive(Resource, Debug, Clone)]
@@ -27,8 +28,8 @@ pub struct GameStateResource(pub GameState);
 /// This prevents accidental drags on quick taps, especially on touch screens.
 #[derive(Resource, Debug, Clone)]
 pub struct DragState {
-    /// IDs of the cards being dragged (bottom-to-top stacking order).
-    pub cards: Vec<u32>,
+    /// Cards being dragged (bottom-to-top stacking order).
+    pub cards: Vec<Card>,
    /// Pile the drag originated from.
    pub origin_pile: Option<KlondikePile>,
    /// World-space offset from the cursor/touch to the bottom card's centre.
@@ -147,8 +147,13 @@ fn apply_safe_area_bottom_anchors(
    }
 }

-/// Pads the bottom of every [`ModalScrim`] by the logical bottom inset so
-/// modal cards don't extend into the Android gesture-navigation zone.
+/// Pads both edges of every [`ModalScrim`] by the logical system-bar insets so
+/// modal cards are centred within the usable area (between the status bar at
+/// the top and the gesture-navigation bar at the bottom).
+///
+/// `padding.top` = status-bar inset; `padding.bottom` = gesture-bar inset.
+/// With `align_items: Center` / `justify_content: Center` on the scrim the
+/// `ModalCard` lands at the visual midpoint of the visible content area.
 ///
 /// Fires when [`SafeAreaInsets`] changes (covers the common case of insets
 /// arriving a few frames after app start) AND when a new `ModalScrim` is
@@ -165,8 +170,18 @@ fn apply_safe_area_to_modal_scrims(
    }
    let scale = windows.iter().next().map_or(1.0, |w| w.scale_factor());
    let window_height = windows.iter().next().map_or(800.0, |w| w.height());
+    // Clamp each inset to 25% of screen height so an unexpectedly large OS
+    // value can't push the modal card off the visible area entirely.
+    let top_logical = (insets.top / scale).min(window_height * 0.25);
    let bottom_logical = (insets.bottom / scale).min(window_height * 0.25);
    for mut node in &mut scrims {
+        // Set both edges so the scrim's content box equals the usable area
+        // between the status bar and the gesture/navigation bar. With
+        // `align_items: Center` / `justify_content: Center` on the scrim,
+        // the modal card is centred within that usable region rather than
+        // the full viewport, correcting the slight upward shift seen when
+        // only the bottom inset was applied.
+        node.padding.top = Val::Px(top_logical);
        node.padding.bottom = Val::Px(bottom_logical);
    }
 }
@@ -253,53 +268,35 @@ mod android {
        }
    }

-    /// Resets the inset poller and clears cached insets on
-    /// `AppLifecycle::WillResume` so that `refresh_insets` re-queries JNI in the
-    /// frames immediately after the app returns to the foreground.
+    /// Resets the inset poller on `AppLifecycle::WillResume` so that
+    /// `refresh_insets` re-queries JNI in the frames immediately after the app
+    /// returns to the foreground.
    ///
-    /// Clearing `SafeAreaInsets` to the default (all-zero) fires
-    /// `on_safe_area_changed` in `table_plugin`, which emits a synthetic
-    /// `WindowResized`.  `on_window_resized` then recomputes the layout;
-    /// once `refresh_insets` resolves the real values a second synthetic
-    /// `WindowResized` fires and the layout converges to the correct position.
+    /// The cached `SafeAreaInsets` are intentionally **not** zeroed here.
+    /// Zeroing them would cause two layout recomputes on every resume:
+    /// once with zero insets (wrong position) and again when JNI resolves the
+    /// real values — visible as a flash.  By preserving the last-known values
+    /// the layout remains stable; if JNI returns a different value (e.g. after
+    /// a rotation) the single update that fires when `SafeAreaInsets` actually
+    /// changes is enough.
    pub(super) fn rearm_on_resumed(
        mut lifecycle: MessageReader<AppLifecycle>,
        mut poll: ResMut<SafeAreaPollTries>,
-        mut insets: ResMut<SafeAreaInsets>,
    ) {
        for event in lifecycle.read() {
            if matches!(event, AppLifecycle::WillResume) {
                poll.0 = 0;
-                *insets = SafeAreaInsets::default();
            }
        }
    }

    fn query_insets() -> Result<SafeAreaInsets, String> {
-        use bevy::android::ANDROID_APP;
-        use jni::{JavaVM, objects::JObject};
+        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 JavaVM* set up by the Android
-        // runtime; valid for the lifetime of the process.
-        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()` returns 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<SafeAreaInsets> {
+        android_jni::with_activity_env(|env, activity| {
            // Window window = activity.getWindow();
            let window = env
-                .call_method(&activity, "getWindow", "()Landroid/view/Window;", &[])?
+                .call_method(activity, "getWindow", "()Landroid/view/Window;", &[])?
                .l()?;

            // View decor = window.getDecorView();
@@ -351,8 +348,7 @@ mod android {
                left,
                right,
            })
-        })()
-        .map_err(|e| format!("safe-area JNI: {e}"))
+        })
    }
 }

@@ -37,11 +37,11 @@

 use bevy::input::ButtonInput;
 use bevy::prelude::*;
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::card::Card;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::Card;
 use solitaire_core::game_state::GameState;

-use crate::card_plugin::CardEntity;
+use crate::card_plugin::CardEntityIndex;
 use crate::events::{InfoToastEvent, MoveRequestEvent, StateChangedEvent};
 use crate::game_plugin::GameMutation;
 use crate::input_plugin::{best_destination, best_tableau_destination_for_stack};
@@ -91,9 +91,9 @@ pub enum KeyboardDragState {
        /// Number of cards lifted (1 for waste / foundation, full face-up
        /// run length for a tableau column).
        count: usize,
-        /// Card ids being lifted, in the same bottom-to-top order
+        /// Cards being lifted, in the same bottom-to-top order
        /// `DragState.cards` expects.
-        cards: Vec<u32>,
+        cards: Vec<Card>,
        /// Pre-computed list of piles the lifted stack can legally be
        /// placed on. Always at least one entry while in this variant —
        /// if no legal destinations exist the state machine refuses to
@@ -147,8 +147,12 @@ pub struct SelectionPlugin;

 impl Plugin for SelectionPlugin {
    fn build(&self, app: &mut App) {
+        // `CardEntityIndex` is owned and kept current by `CardPlugin`; this
+        // call is a no-op there. It is declared here so `update_selection_highlight`
+        // can read it via `Res<>` even in harnesses that omit `CardPlugin`.
        app.init_resource::<SelectionState>()
            .init_resource::<KeyboardDragState>()
+            .init_resource::<CardEntityIndex>()
            .add_systems(
                Update,
                (
@@ -159,7 +163,7 @@ impl Plugin for SelectionPlugin {
                    update_selection_highlight.after(GameMutation).run_if(
                        resource_changed::<SelectionState>
                            .or(resource_changed::<KeyboardDragState>)
-                            .or(resource_changed::<crate::GameStateResource>),
+                            .or(resource_changed::<GameStateResource>),
                    ),
                ),
            );
@@ -202,7 +206,10 @@ fn cycled_piles() -> Vec<KlondikePile> {
 ///
 /// If `current` is `None` the first available pile is returned.
 /// If `available` is empty, `None` is returned.
-pub fn cycle_next_pile(available: &[KlondikePile], current: Option<&KlondikePile>) -> Option<KlondikePile> {
+pub fn cycle_next_pile(
+    available: &[KlondikePile],
+    current: Option<&KlondikePile>,
+) -> Option<KlondikePile> {
    if available.is_empty() {
        return None;
    }
@@ -235,7 +242,11 @@ pub fn cycle_next_pile(available: &[KlondikePile], current: Option<&KlondikePile
 ///
 /// Both `current` and `next` must be `Some`; if either is `None` this returns
 /// `false`.
-fn did_wrap(available: &[KlondikePile], current: Option<&KlondikePile>, next: Option<&KlondikePile>) -> bool {
+fn did_wrap(
+    available: &[KlondikePile],
+    current: Option<&KlondikePile>,
+    next: Option<&KlondikePile>,
+) -> bool {
    let (Some(cur), Some(nxt)) = (current, next) else {
        return false;
    };
@@ -386,9 +397,7 @@ fn handle_selection_keys(
            KlondikePile::Tableau(Tableau::Tableau7),
        ];
        all.into_iter()
-            .filter(|p| {
-                pile_cards(&game.0, p).last().is_some_and(|c| c.face_up)
-            })
+            .filter(|p| pile_cards(&game.0, p).last().is_some_and(|c| c.1))
            .collect()
    };

@@ -419,7 +428,7 @@ fn handle_selection_keys(
        && let Some(ref pile) = selection.selected_pile
    {
        let selected_cards = pile_cards(&game.0, pile);
-        let Some(card) = selected_cards.last().filter(|c| c.face_up) else {
+        let Some((card, _)) = selected_cards.last().filter(|c| c.1) else {
            return;
        };
        // Priority 1: foundation move (single card).
@@ -436,7 +445,7 @@ fn handle_selection_keys(
        let run_len = face_up_run_len(&selected_cards);
        let bottom_card = selected_cards
            .get(selected_cards.len().saturating_sub(run_len))
-            .cloned();
+            .map(|(c, _)| c.clone());
        if let Some(bottom) = bottom_card
            && let Some((dest, count)) =
                best_tableau_destination_for_stack(&bottom, pile, &game.0, run_len)
@@ -478,8 +487,9 @@ fn handle_selection_keys(
            1
        };
        let start = source_cards.len().saturating_sub(count);
-        let lifted_cards: Vec<u32> = source_cards[start..].iter().map(|c| c.id).collect();
-        let Some(bottom) = source_cards.get(start) else {
+        let lifted_cards: Vec<Card> =
+            source_cards[start..].iter().map(|(c, _)| c.clone()).collect();
+        let Some((bottom, _)) = source_cards.get(start) else {
            return;
        };
        let legal = legal_destinations_for(bottom, source, &game.0, count);
@@ -524,7 +534,7 @@ fn handle_selection_keys(
 /// destination after a lift. Players who want a different column simply
 /// press the right-arrow key once or twice.
 pub(crate) fn legal_destinations_for(
-    _bottom: &solitaire_core::card::Card,
+    _bottom: &Card,
    source: &KlondikePile,
    game: &GameState,
    stack_count: usize,
@@ -569,10 +579,10 @@ pub(crate) fn legal_destinations_for(
 /// Walks backwards from the last element and stops at the first face-down card
 /// (or when the slice is exhausted). Returns at least `1` when the top card is
 /// face-up; returns `0` for an empty slice or when the top card is face-down.
-fn face_up_run_len(cards: &[solitaire_core::card::Card]) -> usize {
+fn face_up_run_len(cards: &[(Card, bool)]) -> usize {
    let mut count = 0;
-    for card in cards.iter().rev() {
-        if card.face_up {
+    for (_, face_up) in cards.iter().rev() {
+        if *face_up {
            count += 1;
        } else {
            break;
@@ -588,10 +598,10 @@ fn face_up_run_len(cards: &[solitaire_core::card::Card]) -> usize {
 /// handler can attempt a foundation move first and fall through to a
 /// multi-card stack move rather than accepting a single-card tableau move.
 fn try_foundation_dest(
-    card: &solitaire_core::card::Card,
-    game: &solitaire_core::game_state::GameState,
+    card: &Card,
+    game: &GameState,
 ) -> Option<KlondikePile> {
-    let source = game.pile_containing_card(card.id)?;
+    let source = game.pile_containing_card(card.clone())?;
    for foundation in [
        Foundation::Foundation1,
        Foundation::Foundation2,
@@ -651,7 +661,7 @@ fn update_selection_highlight(
    kbd_drag: Res<KeyboardDragState>,
    game: Res<GameStateResource>,
    layout: Option<Res<LayoutResource>>,
-    card_entities: Query<(Entity, &CardEntity)>,
+    card_index: Res<CardEntityIndex>,
    highlights: Query<Entity, With<SelectionHighlight>>,
 ) {
    // Always despawn any existing highlight first.
@@ -689,8 +699,8 @@ fn update_selection_highlight(
    {
        spawn_highlight_on_card(
            &mut commands,
-            &card_entities,
-            card.id,
+            &card_index,
+            &card,
            card_size,
            source_color,
        );
@@ -706,8 +716,8 @@ fn update_selection_highlight(
        if let Some(card) = top_face_up_card(dest, &game.0) {
            spawn_highlight_on_card(
                &mut commands,
-                &card_entities,
-                card.id,
+                &card_index,
+                &card,
                card_size,
                dest_color,
            );
@@ -717,14 +727,14 @@ fn update_selection_highlight(

 /// Returns the top face-up card on `pile`, or `None` if the pile is
 /// empty or its top card is face-down.
-fn top_face_up_card(
-    pile: &KlondikePile,
-    game: &GameState,
-) -> Option<Card> {
-    pile_cards(game, pile).last().filter(|c| c.face_up).cloned()
+fn top_face_up_card(pile: &KlondikePile, game: &GameState) -> Option<Card> {
+    pile_cards(game, pile)
+        .last()
+        .filter(|(_, up)| *up)
+        .map(|(c, _)| c.clone())
 }

-fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<Card> {
+fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<(Card, bool)> {
    match pile {
        KlondikePile::Stock => game.waste_cards(),
        _ => game.pile(*pile),
@@ -732,30 +742,27 @@ fn pile_cards(game: &GameState, pile: &KlondikePile) -> Vec<Card> {
 }

 /// Spawn a `SelectionHighlight` sprite as a child of the entity carrying
-/// the matching `CardEntity::card_id`. No-op if no entity matches.
+/// the matching `CardEntity::card`. No-op if no entity matches.
 fn spawn_highlight_on_card(
    commands: &mut Commands,
-    card_entities: &Query<(Entity, &CardEntity)>,
-    card_id: u32,
+    card_index: &CardEntityIndex,
+    card: &Card,
    card_size: Vec2,
    color: Color,
 ) {
-    for (entity, card_entity) in card_entities {
-        if card_entity.card_id == card_id {
-            commands.entity(entity).with_children(|b| {
-                b.spawn((
-                    SelectionHighlight,
-                    Sprite {
-                        color,
-                        custom_size: Some(card_size + Vec2::splat(4.0)),
-                        ..default()
-                    },
-                    Transform::from_xyz(0.0, 0.0, -0.01),
-                    Visibility::default(),
-                ));
-            });
-            break;
-        }
+    if let Some(entity) = card_index.get(card) {
+        commands.entity(entity).with_children(|b| {
+            b.spawn((
+                SelectionHighlight,
+                Sprite {
+                    color,
+                    custom_size: Some(card_size + Vec2::splat(4.0)),
+                    ..default()
+                },
+                Transform::from_xyz(0.0, 0.0, -0.01),
+                Visibility::default(),
+            ));
+        });
    }
 }

@@ -879,58 +886,23 @@ mod tests {

    #[test]
    fn face_up_run_len_all_face_up() {
-        use solitaire_core::card::{Card, Rank, Suit};
+        use solitaire_core::{Card, Deck, Rank, Suit};
        let cards = vec![
-            Card {
-                id: 0,
-                suit: Suit::Clubs,
-                rank: Rank::King,
-                face_up: true,
-            },
-            Card {
-                id: 1,
-                suit: Suit::Hearts,
-                rank: Rank::Queen,
-                face_up: true,
-            },
-            Card {
-                id: 2,
-                suit: Suit::Spades,
-                rank: Rank::Jack,
-                face_up: true,
-            },
+            (Card::new(Deck::Deck1, Suit::Clubs, Rank::King), true),
+            (Card::new(Deck::Deck1, Suit::Hearts, Rank::Queen), true),
+            (Card::new(Deck::Deck1, Suit::Spades, Rank::Jack), true),
        ];
        assert_eq!(face_up_run_len(&cards), 3);
    }

    #[test]
    fn face_up_run_len_mixed_stops_at_face_down() {
-        use solitaire_core::card::{Card, Rank, Suit};
+        use solitaire_core::{Card, Deck, Rank, Suit};
        let cards = vec![
-            Card {
-                id: 0,
-                suit: Suit::Clubs,
-                rank: Rank::King,
-                face_up: false,
-            },
-            Card {
-                id: 1,
-                suit: Suit::Hearts,
-                rank: Rank::Queen,
-                face_up: false,
-            },
-            Card {
-                id: 2,
-                suit: Suit::Spades,
-                rank: Rank::Jack,
-                face_up: true,
-            },
-            Card {
-                id: 3,
-                suit: Suit::Diamonds,
-                rank: Rank::Ten,
-                face_up: true,
-            },
+            (Card::new(Deck::Deck1, Suit::Clubs, Rank::King), false),
+            (Card::new(Deck::Deck1, Suit::Hearts, Rank::Queen), false),
+            (Card::new(Deck::Deck1, Suit::Spades, Rank::Jack), true),
+            (Card::new(Deck::Deck1, Suit::Diamonds, Rank::Ten), true),
        ];
        // Only the top two cards are face-up.
        assert_eq!(face_up_run_len(&cards), 2);
@@ -938,33 +910,18 @@ mod tests {

    #[test]
    fn face_up_run_len_top_card_face_down_is_zero() {
-        use solitaire_core::card::{Card, Rank, Suit};
+        use solitaire_core::{Card, Deck, Rank, Suit};
        let cards = vec![
-            Card {
-                id: 0,
-                suit: Suit::Clubs,
-                rank: Rank::King,
-                face_up: true,
-            },
-            Card {
-                id: 1,
-                suit: Suit::Hearts,
-                rank: Rank::Queen,
-                face_up: false,
-            },
+            (Card::new(Deck::Deck1, Suit::Clubs, Rank::King), true),
+            (Card::new(Deck::Deck1, Suit::Hearts, Rank::Queen), false),
        ];
        assert_eq!(face_up_run_len(&cards), 0);
    }

    #[test]
    fn face_up_run_len_single_face_up_card() {
-        use solitaire_core::card::{Card, Rank, Suit};
-        let cards = vec![Card {
-            id: 0,
-            suit: Suit::Hearts,
-            rank: Rank::Ace,
-            face_up: true,
-        }];
+        use solitaire_core::{Card, Deck, Rank, Suit};
+        let cards = vec![(Card::new(Deck::Deck1, Suit::Hearts, Rank::Ace), true)];
        assert_eq!(face_up_run_len(&cards), 1);
    }

@@ -977,8 +934,8 @@ mod tests {
    // -----------------------------------------------------------------------

    use bevy::ecs::message::Messages;
-    use solitaire_core::card::{Card, Rank, Suit};
-    use solitaire_core::game_state::{DrawMode, GameState};
+    use solitaire_core::{Card, Deck, Rank, Suit};
+    use solitaire_core::{DrawStockConfig, game_state::GameState};

    /// Build a minimal app with `SelectionPlugin` only — no GamePlugin, no
    /// AssetServer. The `MoveRequestEvent` / `StateChangedEvent` /
@@ -1011,7 +968,7 @@ mod tests {
    /// Ace first). It cannot go to an empty tableau (only Kings).
    /// Empty tableaus T3..T6 only accept Kings, so they are filtered out.
    fn deterministic_state() -> GameState {
-        let mut g = GameState::new(0, DrawMode::DrawOne);
+        let mut g = GameState::new(0, DrawStockConfig::DrawOne);
        // Clear stock, waste, all tableaus.
        g.set_test_stock_cards(Vec::new());
        g.set_test_waste_cards(Vec::new());
@@ -1029,30 +986,15 @@ mod tests {
        // Place test cards.
        g.set_test_tableau_cards(
            Tableau::Tableau1,
-            vec![Card {
-                id: 100,
-                suit: Suit::Clubs,
-                rank: Rank::Five,
-                face_up: true,
-            }],
+            vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Five)],
        );
        g.set_test_tableau_cards(
            Tableau::Tableau2,
-            vec![Card {
-                id: 101,
-                suit: Suit::Hearts,
-                rank: Rank::Six,
-                face_up: true,
-            }],
+            vec![Card::new(Deck::Deck1, Suit::Hearts, Rank::Six)],
        );
        g.set_test_tableau_cards(
            Tableau::Tableau3,
-            vec![Card {
-                id: 102,
-                suit: Suit::Diamonds,
-                rank: Rank::Six,
-                face_up: true,
-            }],
+            vec![Card::new(Deck::Deck1, Suit::Diamonds, Rank::Six)],
        );
        g
    }
@@ -1108,8 +1050,7 @@ mod tests {
        let selected = app
            .world()
            .resource::<SelectionState>()
-            .selected_pile
-            .clone();
+            .selected_pile;
        // The cycle order starts at Waste, but Waste is empty so the next
        // available pile (Tableau(0)) is selected.
        assert_eq!(selected, Some(KlondikePile::Tableau(Tableau::Tableau1)));
@@ -1149,7 +1090,7 @@ mod tests {
            } => {
                assert_eq!(source_pile, KlondikePile::Tableau(Tableau::Tableau1));
                assert_eq!(count, 1);
-                assert_eq!(cards, vec![100]);
+                assert_eq!(cards, vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Five)]);
                assert!(
                    !legal_destinations.is_empty(),
                    "lifted stack must have at least one legal destination"
@@ -1161,15 +1102,21 @@ mod tests {

        // DragState must mirror the lifted cards and carry the keyboard sentinel.
        let drag = app.world().resource::<DragState>();
-        assert_eq!(drag.cards, vec![100]);
-        assert_eq!(drag.origin_pile, Some(KlondikePile::Tableau(Tableau::Tableau1)));
+        assert_eq!(
+            drag.cards,
+            vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Five)]
+        );
+        assert_eq!(
+            drag.origin_pile,
+            Some(KlondikePile::Tableau(Tableau::Tableau1))
+        );
        assert_eq!(drag.active_touch_id, Some(KEYBOARD_DRAG_TOUCH_ID));
    }

    /// Test 3 — Arrow keys in `Lifted` cycle through *legal* destinations
    /// only (foundations and tableaus that pass `can_place_on_*`), and
    /// wrap at the end of the list.
-        /// Test 4 — Enter while `Lifted` with a destination focused fires
+    /// Test 4 — Enter while `Lifted` with a destination focused fires
    /// exactly one `MoveRequestEvent` and resets the state machine to
    /// `Idle` with `DragState` cleared.
    #[test]
@@ -1263,7 +1210,7 @@ mod tests {
        // keyboard sentinel.
        {
            let mut drag = app.world_mut().resource_mut::<DragState>();
-            drag.cards = vec![100];
+            drag.cards = vec![Card::new(Deck::Deck1, Suit::Clubs, Rank::Five)];
            drag.origin_pile = Some(KlondikePile::Tableau(Tableau::Tableau1));
            drag.committed = true;
            drag.active_touch_id = None;
@@ -1272,15 +1219,13 @@ mod tests {
        let before = app
            .world()
            .resource::<SelectionState>()
-            .selected_pile
-            .clone();
+            .selected_pile;
        press_key(&mut app, KeyCode::Tab);
        app.update();
        let after = app
            .world()
            .resource::<SelectionState>()
-            .selected_pile
-            .clone();
+            .selected_pile;

        assert_eq!(
            before, after,
@@ -15,7 +15,7 @@ use bevy::input::mouse::{MouseScrollUnit, MouseWheel};
 use bevy::prelude::*;
 use bevy::ui::{ComputedNode, UiGlobalTransform};
 use bevy::window::{WindowMoved, WindowResized};
-use solitaire_core::game_state::DrawMode;
+use solitaire_core::DrawStockConfig;
 use solitaire_data::{
    AnimSpeed, REPLAY_MOVE_INTERVAL_STEP_SECS, Settings, TIME_BONUS_MULTIPLIER_STEP,
    TOOLTIP_DELAY_STEP_SECS, WindowGeometry, load_settings_from, save_settings_to, settings::Theme,
@@ -33,9 +33,9 @@ use crate::events::{
 use crate::font_plugin::FontResource;
 use crate::progress_plugin::ProgressResource;
 use crate::resources::{SettingsScrollPos, SyncStatus, SyncStatusResource};
-use crate::theme::{ThemeThumbnailCache, ThemeThumbnailPair};
 #[cfg(not(target_arch = "wasm32"))]
 use crate::theme::{ImportError, import_theme, refresh_registry};
+use crate::theme::{ThemeThumbnailCache, ThemeThumbnailPair};
 use crate::ui_focus::{FocusGroup, FocusRow, Focusable, FocusedButton};
 use crate::ui_modal::{
    ButtonVariant, ModalButton, ModalScrim, spawn_modal, spawn_modal_actions, spawn_modal_button,
@@ -241,7 +241,7 @@ enum SettingsButton {
    ToggleTouchInputMode,
    /// Toggle the [`Settings::winnable_deals_only`] flag. When on, new
    /// random Classic-mode deals are filtered through
-    /// [`solitaire_core::solver::try_solve`] until one is provably
+    /// [`solitaire_core::game_state::GameState::solve_fresh_deal`] until one is provably
    /// winnable (or the retry cap is hit). Off by default.
    ToggleWinnableDealsOnly,
    /// Toggle the inverse of [`Settings::disable_smart_default_size`].
@@ -252,8 +252,7 @@ enum SettingsButton {
    /// player's last window size always wins.
    ToggleSmartDefaultSize,
    /// Toggle [`Settings::analytics_enabled`]. Only rendered when a
-    /// sync server is configured — there is no server to send to in
-    /// local-only mode.
+    /// Matomo URL is configured.
    ToggleAnalytics,
    /// Scan `user_theme_dir()` for new `.zip` files and import each one.
    #[cfg(not(target_arch = "wasm32"))]
@@ -380,8 +379,8 @@ impl Plugin for SettingsPlugin {
            .add_message::<DeleteAccountRequestEvent>()
            .add_message::<ToggleSettingsRequestEvent>()
            .add_message::<InfoToastEvent>()
-            .add_message::<bevy::input::mouse::MouseWheel>()
-            .add_message::<bevy::input::touch::TouchInput>()
+            .add_message::<MouseWheel>()
+            .add_message::<TouchInput>()
            // `WindowResized` / `WindowMoved` are real Bevy window events
            // and emitted by the windowing backend under `DefaultPlugins`,
            // but we register them explicitly here so the geometry watcher
@@ -1087,8 +1086,8 @@ fn handle_settings_buttons(
            }
            SettingsButton::ToggleDrawMode => {
                settings.0.draw_mode = match settings.0.draw_mode {
-                    DrawMode::DrawOne => DrawMode::DrawThree,
-                    DrawMode::DrawThree => DrawMode::DrawOne,
+                    DrawStockConfig::DrawOne => DrawStockConfig::DrawThree,
+                    DrawStockConfig::DrawThree => DrawStockConfig::DrawOne,
                };
                persist(&path, &settings.0);
                changed.write(SettingsChangedEvent(settings.0.clone()));
@@ -1311,10 +1310,10 @@ fn handle_sync_buttons(
    }
 }

-fn draw_mode_label(mode: &DrawMode) -> String {
+fn draw_mode_label(mode: &DrawStockConfig) -> String {
    match mode {
-        DrawMode::DrawOne => "Draw 1".into(),
-        DrawMode::DrawThree => "Draw 3".into(),
+        DrawStockConfig::DrawOne => "Draw 1".into(),
+        DrawStockConfig::DrawThree => "Draw 3".into(),
    }
 }

@@ -2663,7 +2662,7 @@ fn handle_scan_themes(

        let themes_dir = user_theme_dir();

-        let zips: Vec<std::path::PathBuf> = match std::fs::read_dir(&themes_dir) {
+        let zips: Vec<PathBuf> = match std::fs::read_dir(&themes_dir) {
            Ok(entries) => entries
                .flatten()
                .map(|e| e.path())
@@ -3020,7 +3019,7 @@ mod tests {
            unit: MouseScrollUnit::Line,
            x: 0.0,
            y: -3.0,
-            window: bevy::ecs::entity::Entity::PLACEHOLDER,
+            window: Entity::PLACEHOLDER,
        });
        app.update();
        // ScrollPosition must remain at 0.0 — panel was closed.
@@ -3053,7 +3052,7 @@ mod tests {
            unit: MouseScrollUnit::Line,
            x: 0.0,
            y: -2.0,
-            window: bevy::ecs::entity::Entity::PLACEHOLDER,
+            window: Entity::PLACEHOLDER,
        });
        app.update();
        let offset = app
@@ -3365,7 +3364,7 @@ mod tests {

    fn fire_resize(app: &mut App, width: f32, height: f32) {
        app.world_mut().write_message(WindowResized {
-            window: bevy::ecs::entity::Entity::PLACEHOLDER,
+            window: Entity::PLACEHOLDER,
            width,
            height,
        });
@@ -3373,7 +3372,7 @@ mod tests {

    fn fire_move(app: &mut App, x: i32, y: i32) {
        app.world_mut().write_message(WindowMoved {
-            window: bevy::ecs::entity::Entity::PLACEHOLDER,
+            window: Entity::PLACEHOLDER,
            position: IVec2::new(x, y),
        });
    }
@@ -3495,7 +3494,7 @@ mod tests {
            unit: MouseScrollUnit::Line,
            x: 0.0,
            y: 5.0,
-            window: bevy::ecs::entity::Entity::PLACEHOLDER,
+            window: Entity::PLACEHOLDER,
        });
        app.update();
        let offset = app
@@ -1010,8 +1010,8 @@ mod tests {
        use solitaire_data::Settings;
        let mut app = App::new();
        app.add_plugins(MinimalPlugins)
-            .add_plugins(bevy::asset::AssetPlugin::default())
-            .init_asset::<bevy::image::Image>()
+            .add_plugins(AssetPlugin::default())
+            .init_asset::<Image>()
            .add_plugins(SplashPlugin);
        app.init_resource::<ButtonInput<KeyCode>>();
        app.init_resource::<ButtonInput<MouseButton>>();
@@ -203,7 +203,7 @@ impl Plugin for StatsPlugin {
            // `DefaultPlugins`; register it explicitly so the stats-scroll
            // system also runs cleanly under `MinimalPlugins` in tests.
            .add_message::<MouseWheel>()
-            .add_message::<bevy::input::touch::TouchInput>()
+            .add_message::<TouchInput>()
            // record_abandoned must read `move_count` BEFORE handle_new_game
            // clobbers it with a fresh game. These are NOT in StatsUpdate because
            // StatsUpdate (as a set) is ordered after GameMutation by external
@@ -464,7 +464,7 @@ fn repaint_replay_selector_detail(
 /// Pure helper: render the detail line for the selected replay. Returns
 /// `"{duration} win on {date}"` plus a `" \u{2022} Shareable"` badge
 /// when a share URL is present. Empty when the history slice is empty.
-pub fn replay_selector_detail(replays: &[solitaire_data::Replay], index: usize) -> String {
+pub fn replay_selector_detail(replays: &[Replay], index: usize) -> String {
    let Some(r) = replays.get(index.min(replays.len().saturating_sub(1))) else {
        return String::new();
    };
@@ -534,7 +534,7 @@ fn update_stats_on_win(
    let prev_streak = stats.0.win_streak_current;
    stats
        .0
-        .update_on_win(ev.score, ev.time_seconds, &game.0.draw_mode);
+        .update_on_win(ev.score, ev.time_seconds, &game.0.draw_mode());
    // Per-mode best score / fastest win — additive on top of the
    // lifetime totals tracked by `update_on_win`. TimeAttack is a
    // no-op inside the helper because it has its own session-level
@@ -588,7 +588,7 @@ fn update_stats_on_new_game(
    mut toast: MessageWriter<InfoToastEvent>,
 ) {
    for _ in events.read() {
-        if game.0.move_count > 0 && !game.0.is_won {
+        if game.0.move_count() > 0 && !game.0.is_won() {
            let streak = stats.0.win_streak_current;
            stats.0.record_abandoned();
            persist(&path, &stats.0, "abandoned game");
@@ -614,7 +614,7 @@ fn handle_forfeit(
    mut auto_complete: Option<ResMut<AutoCompleteState>>,
 ) {
    for _ in events.read() {
-        if game.0.move_count > 0 && !game.0.is_won {
+        if game.0.move_count() > 0 && !game.0.is_won() {
            let streak = stats.0.win_streak_current;
            stats.0.record_abandoned();
            persist(&path, &stats.0, "forfeit");
@@ -1325,9 +1325,9 @@ mod tests {
    fn draw_three_win_increments_draw_three_wins_only() {
        let mut app = headless_app();
        app.world_mut()
-            .resource_mut::<crate::resources::GameStateResource>()
+            .resource_mut::<GameStateResource>()
            .0
-            .draw_mode = solitaire_core::game_state::DrawMode::DrawThree;
+            .set_test_draw_mode(solitaire_core::DrawStockConfig::DrawThree);

        app.world_mut().write_message(GameWonEvent {
            score: 500,
@@ -1371,9 +1371,9 @@ mod tests {
        let mut app = headless_app();

        app.world_mut()
-            .resource_mut::<crate::resources::GameStateResource>()
+            .resource_mut::<GameStateResource>()
            .0
-            .move_count = 3;
+            .set_test_move_count(3);

        app.world_mut().write_message(NewGameRequestEvent {
            seed: Some(999),
@@ -1501,7 +1501,7 @@ mod tests {
    fn zen_win_event_updates_zen_best_score_only() {
        let mut app = headless_app();
        app.world_mut()
-            .resource_mut::<crate::resources::GameStateResource>()
+            .resource_mut::<GameStateResource>()
            .0
            .mode = solitaire_core::game_state::GameMode::Zen;

@@ -1697,9 +1697,9 @@ mod tests {
            stats.0.win_streak_current = 3;
        }
        app.world_mut()
-            .resource_mut::<crate::resources::GameStateResource>()
+            .resource_mut::<GameStateResource>()
            .0
-            .move_count = 1;
+            .set_test_move_count(1);

        app.world_mut().write_message(ForfeitEvent);
        app.update();
@@ -1723,9 +1723,9 @@ mod tests {
            stats.0.win_streak_current = 1;
        }
        app.world_mut()
-            .resource_mut::<crate::resources::GameStateResource>()
+            .resource_mut::<GameStateResource>()
            .0
-            .move_count = 1;
+            .set_test_move_count(1);

        app.world_mut().write_message(ForfeitEvent);
        app.update();
@@ -1948,11 +1948,11 @@ mod tests {
    ///
    /// Uses a fixed seed, DrawOne mode, Classic game, 2026-05-08 date.
    /// `time_seconds` and `share_url` are the only varying fields across tests.
-    fn make_test_replay(time_seconds: u64, share_url: Option<String>) -> solitaire_data::Replay {
+    fn make_test_replay(time_seconds: u64, share_url: Option<String>) -> Replay {
        let date = chrono::NaiveDate::from_ymd_opt(2026, 5, 8).expect("valid date");
-        let mut r = solitaire_data::Replay::new(
+        let mut r = Replay::new(
            1,
-            solitaire_core::game_state::DrawMode::DrawOne,
+            solitaire_core::DrawStockConfig::DrawOne,
            solitaire_core::game_state::GameMode::Classic,
            time_seconds,
            0,
@@ -3,8 +3,8 @@
 //! On startup, the plugin spawns an async pull task on [`AsyncComputeTaskPool`]
 //! that fetches the remote payload from the active [`SyncProvider`]. Once the
 //! task resolves, the merged result is written to disk and the in-world
-//! resources are updated. On app exit, a blocking push sends the current local
-//! state to the backend.
+//! resources are updated. On app exit, a best-effort async push sends the
+//! current local state to the backend without blocking the Bevy main thread.
 //!
 //! The plugin is completely backend-agnostic: the caller (usually
 //! `solitaire_app`) constructs the right [`SyncProvider`] implementation and
@@ -79,8 +79,8 @@ struct PendingReplayUpload(Option<Task<Result<String, SyncError>>>);
 /// - **Update** — polls the task each frame; on completion merges the remote
 ///   payload with local data, persists the result, and updates in-world
 ///   resources.
-/// - **Last** — on [`AppExit`], performs a blocking push of the current local
-///   state to the active backend.
+/// - **Last** — on [`AppExit`], starts a best-effort async push of the current
+///   local state to the active backend without blocking shutdown.
 ///
 /// Construct via [`SyncPlugin::new`], passing any type that implements
 /// [`SyncProvider`].
@@ -272,11 +272,12 @@ fn poll_pull_result(
    }
 }

-/// Last-schedule system: pushes the current local state on [`AppExit`].
+/// Last-schedule system: starts a best-effort push of the current local state
+/// on [`AppExit`] without blocking the Bevy main thread.
 ///
-/// A blocking push is acceptable here — ARCHITECTURE.md §4 explicitly notes
-/// that blocking on exit is permitted because the game loop is already
-/// shutting down.
+/// The detached task may be cut short by process teardown, so local atomic
+/// persistence remains the durable source of truth even if the final remote
+/// push does not complete.
 fn push_on_exit(
    mut exit_events: MessageReader<AppExit>,
    provider: Res<SyncProviderResource>,
@@ -291,20 +292,16 @@ fn push_on_exit(
    exit_events.clear();

    let payload = build_payload(&stats.0, &achievements.0, &progress.0);
-    let result = rt.0.block_on(provider.0.push(&payload));
-    match result {
-        Ok(_) => {}
-        // `UnsupportedPlatform` is the expected response of
-        // `LocalOnlyProvider`; treat it the same as the pull path does —
-        // no backend configured is not a failure.
-        Err(SyncError::UnsupportedPlatform) => {}
-        Err(e) => {
-            // Log real push failures on exit so they appear in crash/log
-            // reports. We cannot surface them to the UI at this point (game
-            // loop is done).
-            warn!("sync push on exit failed: {e}");
-        }
-    }
+    let provider = provider.0.clone();
+    let rt = rt.0.clone();
+    AsyncComputeTaskPool::get()
+        .spawn(async move {
+            match rt.block_on(provider.push(&payload)) {
+                Ok(_) | Err(SyncError::UnsupportedPlatform) => {}
+                Err(e) => warn!("sync push on exit failed: {e}"),
+            }
+        })
+        .detach();
 }

 /// Update-schedule system: on each `GameWonEvent` push the just-completed
@@ -334,7 +331,7 @@ fn push_replay_on_win(
        }
        let replay = Replay::new(
            game.0.seed,
-            game.0.draw_mode,
+            game.0.draw_mode(),
            game.0.mode,
            ev.time_seconds,
            ev.score,
@@ -499,7 +496,7 @@ mod tests {
            .add_plugins(crate::achievement_plugin::AchievementPlugin::headless())
            .add_plugins(SyncPlugin::new(provider));
        // MinimalPlugins does not register keyboard input.
-        app.init_resource::<bevy::input::ButtonInput<KeyCode>>();
+        app.init_resource::<ButtonInput<KeyCode>>();
        app.update();
        app
    }
@@ -607,7 +604,7 @@ mod tests {
    /// would silently drop the link.
    #[test]
    fn upload_result_writes_share_url_into_replay_and_persists() {
-        use solitaire_core::game_state::{DrawMode, GameMode};
+        use solitaire_core::{DrawStockConfig, game_state::GameMode};
        use solitaire_data::{
            Replay, ReplayHistory, load_replay_history_from, save_replay_history_to,
        };
@@ -620,7 +617,7 @@ mod tests {
        // share_url — the upload-poll path must populate it.
        let initial = Replay::new(
            42,
-            DrawMode::DrawOne,
+            DrawStockConfig::DrawOne,
            GameMode::Classic,
            60,
            500,
@@ -632,8 +629,8 @@ mod tests {
            replays: vec![initial],
        };
        save_replay_history_to(&path, &history).expect("seed history on disk");
-        app.insert_resource(crate::stats_plugin::ReplayHistoryResource(history));
-        app.insert_resource(crate::stats_plugin::LatestReplayPath(Some(path.clone())));
+        app.insert_resource(ReplayHistoryResource(history));
+        app.insert_resource(LatestReplayPath(Some(path.clone())));

        // Pre-resolved task carrying the URL the production path would
        // get back from the server.
@@ -662,7 +659,7 @@ mod tests {
        // In-memory contract: replays[0].share_url is now Some(url).
        let live = app
            .world()
-            .resource::<crate::stats_plugin::ReplayHistoryResource>();
+            .resource::<ReplayHistoryResource>();
        assert_eq!(
            live.0.replays.first().and_then(|r| r.share_url.clone()),
            Some(url.clone()),
@@ -6,14 +6,12 @@

 use bevy::prelude::*;
 use bevy::window::WindowResized;
-use klondike::{Foundation, KlondikePile, Tableau};
-use solitaire_core::card::Suit;
+use solitaire_core::{Foundation, KlondikePile, Tableau};
+use solitaire_core::Suit;

 use crate::events::{HintVisualEvent, StateChangedEvent};
 use crate::hud_plugin::HudVisibility;
-#[cfg(test)]
-use crate::layout::TABLE_COLOUR;
-use crate::layout::{Layout, LayoutResource, LayoutSystem, compute_layout};
+use crate::layout::{Layout, LayoutResource, LayoutSystem, TABLE_COLOUR, compute_layout};
 use crate::resources::GameStateResource;
 use crate::safe_area::SafeAreaInsets;
 use crate::settings_plugin::{SettingsChangedEvent, SettingsResource};
@@ -22,15 +20,28 @@ use crate::ui_theme::TEXT_PRIMARY;
 use solitaire_data::Theme;

 /// Default tint applied to every empty-pile marker sprite. Pure white
-/// at 8% alpha — soft enough that the marker reads as a "hint of a
-/// slot" rather than a panel, but visible against every felt
-/// background.
+/// at 15% alpha — soft enough that the marker reads as a "hint of a
+/// slot" rather than a panel, but discernible even against a very dark
+/// felt background under bright ambient light (the old 8% alpha vanished
+/// on a #151515 felt during on-device Android testing).
 ///
 /// Re-exported as the source of truth for `cursor_plugin::MARKER_DEFAULT`,
 /// which used to duplicate the literal alongside a "kept in sync" doc
 /// comment. Pulling both call sites through this const makes drift a
 /// compile error instead of a stale comment.
-pub const PILE_MARKER_DEFAULT_COLOUR: Color = Color::srgba(1.0, 1.0, 1.0, 0.08);
+pub const PILE_MARKER_DEFAULT_COLOUR: Color = Color::srgba(1.0, 1.0, 1.0, 0.15);
+
+/// Tint applied to the thin outline rectangle sitting behind every
+/// empty-pile marker. A slightly brighter white at 28% alpha gives the
+/// slot a defined edge — the standard solitaire "empty pile" affordance —
+/// without competing with real cards. Rendered as a marginally larger
+/// child rectangle one z-step behind the fill, so the fill overlaps it
+/// and only a hairline frame remains visible.
+const PILE_MARKER_OUTLINE_COLOUR: Color = Color::srgba(1.0, 1.0, 1.0, 0.28);
+
+/// Width in logical pixels of the visible outline frame around an empty
+/// pile marker (the outline rect is this much larger on each side).
+const PILE_MARKER_OUTLINE_WIDTH: f32 = 2.0;

 /// Holds pre-loaded [`Handle<Image>`]s for the 5 selectable table backgrounds.
 ///
@@ -164,9 +175,9 @@ fn setup_table(
            Camera2d,
            Camera {
                clear_color: ClearColorConfig::Custom(Color::srgb(
-                    crate::layout::TABLE_COLOUR[0],
-                    crate::layout::TABLE_COLOUR[1],
-                    crate::layout::TABLE_COLOUR[2],
+                    TABLE_COLOUR[0],
+                    TABLE_COLOUR[1],
+                    TABLE_COLOUR[2],
                )),
                ..default()
            },
@@ -286,6 +297,22 @@ fn spawn_pile_markers(commands: &mut Commands, layout: &Layout) {
            PileMarker(pile),
        ));

+        // Outline frame: a marginally larger rectangle sitting one z-step
+        // behind the fill. The fill overlaps its centre, leaving only a
+        // hairline border visible — a defined slot edge without an extra
+        // asset or 9-slice. Untagged so the `PileMarker` count is unchanged.
+        let outline_size = marker_size + Vec2::splat(PILE_MARKER_OUTLINE_WIDTH * 2.0);
+        entity.with_children(|b| {
+            b.spawn((
+                Sprite {
+                    color: PILE_MARKER_OUTLINE_COLOUR,
+                    custom_size: Some(outline_size),
+                    ..default()
+                },
+                Transform::from_xyz(0.0, 0.0, -0.05),
+            ));
+        });
+
        // Tableau markers show "K" (only a King may start an empty column).
        // Foundation markers show "A" (only an Ace may claim an empty slot).
        // Neither label carries a suit because any suit may start any slot.
@@ -491,7 +518,7 @@ fn sync_pile_marker_visibility(
 fn pile_cards(
    game: &solitaire_core::game_state::GameState,
    pile: &KlondikePile,
-) -> Vec<solitaire_core::card::Card> {
+) -> Vec<(solitaire_core::Card, bool)> {
    match pile {
        KlondikePile::Stock => {
            let stock = game.stock_cards();
@@ -577,7 +604,7 @@ mod tests {
            .world_mut()
            .query::<&PileMarker>()
            .iter(app.world())
-            .map(|m| m.0.clone())
+            .map(|m| m.0)
            .collect();
        types.sort_by_key(|p| format!("{p:?}"));
        types.dedup();
@@ -607,9 +634,9 @@ mod tests {
        let mut visible_piles: Vec<KlondikePile> = Vec::new();
        for (marker, visibility) in q.iter(app.world()) {
            if matches!(visibility, Visibility::Hidden) {
-                hidden_piles.push(marker.0.clone());
+                hidden_piles.push(marker.0);
            } else {
-                visible_piles.push(marker.0.clone());
+                visible_piles.push(marker.0);
            }
        }

@@ -236,7 +236,7 @@ pub fn import_theme_into(zip_path: &Path, target_root: &Path) -> Result<ThemeId,
 /// Sums every entry's declared uncompressed size and rejects archives
 /// that overflow [`MAX_ARCHIVE_BYTES`]. Iterates the central
 /// directory only — does not actually decompress anything.
-fn enforce_archive_size_limit<R: io::Read + io::Seek>(
+fn enforce_archive_size_limit<R: Read + io::Seek>(
    archive: &mut zip::ZipArchive<R>,
 ) -> Result<(), ImportError> {
    let mut total: u64 = 0;
@@ -257,7 +257,7 @@ fn enforce_archive_size_limit<R: io::Read + io::Seek>(
 /// (after normalisation) escapes its root. Catches `..`, absolute
 /// paths, drive prefixes on Windows, and the awkward case where
 /// `enclosed_name` returns `None` because the entry is suspicious.
-fn enforce_zip_slip_safe<R: io::Read + io::Seek>(
+fn enforce_zip_slip_safe<R: Read + io::Seek>(
    archive: &mut zip::ZipArchive<R>,
 ) -> Result<(), ImportError> {
    for i in 0..archive.len() {
@@ -291,7 +291,7 @@ fn is_safe_relative_path(p: &Path) -> bool {
 ///   `theme.ron` entry at its root.
 /// - [`ImportError::ManifestParse`] when the bytes don't form valid
 ///   RON for `ThemeManifest`.
-fn read_manifest<R: io::Read + io::Seek>(
+fn read_manifest<R: Read + io::Seek>(
    archive: &mut zip::ZipArchive<R>,
 ) -> Result<ThemeManifest, ImportError> {
    // We can't use `?` directly across `by_name` because a missing
@@ -318,7 +318,7 @@ fn read_manifest<R: io::Read + io::Seek>(
 ///
 /// Returns [`ImportError::MissingFile`] when the archive has no entry
 /// matching the path.
-fn read_archive_entry<R: io::Read + io::Seek>(
+fn read_archive_entry<R: Read + io::Seek>(
    archive: &mut zip::ZipArchive<R>,
    path: &Path,
 ) -> Result<Vec<u8>, ImportError> {
@@ -351,7 +351,7 @@ fn archive_key(path: &Path) -> String {
 /// parent directories as needed. The destination path is rebuilt from
 /// the safe components we already vetted in
 /// [`enforce_zip_slip_safe`], not from the raw entry name.
-fn write_archive_entry<R: io::Read + io::Seek>(
+fn write_archive_entry<R: Read + io::Seek>(
    archive: &mut zip::ZipArchive<R>,
    name: &str,
    staging: &Path,
@@ -384,7 +384,7 @@ fn write_archive_entry<R: io::Read + io::Seek>(

 /// Variant of [`write_archive_entry`] keyed by `Path` for the
 /// manifest-declared face/back paths.
-fn write_archive_entry_pathbuf<R: io::Read + io::Seek>(
+fn write_archive_entry_pathbuf<R: Read + io::Seek>(
    archive: &mut zip::ZipArchive<R>,
    path: &Path,
    staging: &Path,
@@ -27,7 +27,7 @@ use bevy::reflect::TypePath;
 use serde::{Deserialize, Serialize};
 use thiserror::Error;

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

 #[cfg(not(target_arch = "wasm32"))]
 pub use importer::{ImportError, ThemeId, import_theme, import_theme_into};
@@ -43,11 +43,11 @@ pub use registry::{

 /// Hashable lookup key into [`CardTheme::faces`].
 ///
-/// Distinct from `solitaire_core::Card`: the core type carries an `id`
-/// and a `face_up` flag that vary per deal, neither of which is
-/// relevant to image lookup. `CardKey` is just the (suit, rank) pair
-/// that uniquely identifies which artwork to draw.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+/// Distinct from `card_game::Card`, which also encodes a deck id: `CardKey`
+/// is just the (suit, rank) pair that uniquely identifies which artwork to
+/// draw. Serialised theme manifests address faces by
+/// [`CardKey::manifest_name`] strings, not by serialising `CardKey` itself.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct CardKey {
    pub suit: Suit,
    pub rank: Rank,
@@ -12,7 +12,7 @@ use bevy::asset::AssetEvent;
 use bevy::ecs::message::MessageReader;
 use bevy::math::UVec2;
 use bevy::prelude::*;
-use solitaire_core::card::{Rank, Suit};
+use solitaire_core::{Rank, Suit};

 use crate::assets::{
    bundled_theme_url, classic_theme_svg_bytes, dark_theme_svg_bytes, rasterize_svg, user_theme_dir,
@@ -484,7 +484,7 @@ mod tests {
        let mut image_set = empty_card_image_set();
        // Snapshot the legacy back ids so we can prove they don't
        // change when a theme is applied.
-        let legacy_ids_before: [bevy::asset::AssetId<bevy::image::Image>; 5] =
+        let legacy_ids_before: [AssetId<Image>; 5] =
            std::array::from_fn(|i| image_set.backs[i].id());
        let theme = empty_theme();
        assert!(image_set.theme_back.is_none(), "theme_back starts empty");
@@ -22,9 +22,9 @@
 use std::path::Path;

 use bevy::log::warn;
-use bevy::prelude::{App, Plugin, Resource};
 #[cfg(not(target_arch = "wasm32"))]
 use bevy::prelude::Startup;
+use bevy::prelude::{App, Plugin, Resource};
 use serde::Deserialize;

 use super::ThemeMeta;
--- a/Show More
+++ b/Show More