docs: update repo URL references to corrected Rusty_Solitaire spelling

The GitHub repo was renamed from Rusty_Solitare to Rusty_Solitaire (adding the missing 'i'). The local origin remote has been updated via `git remote set-url`; this commit updates the three doc references that hardcoded the old URL. SESSION_HANDOFF.md's "Canonical remote" section now names the new URL and explains the rename for future readers, including the note that local clone directories may still be named Rusty_Solitare — that's a local-only name and works fine, only the GitHub repo URL changed. docs/SESSION_HANDOFF.md (older snapshot, unchanged otherwise) gets its single URL line corrected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs: refresh SESSION_HANDOFF for session 7 UX-iteration round complete
2026-05-02 00:36:06 +00:00 · 2026-05-02 00:33:42 +00:00 · 2026-05-02 00:31:15 +00:00 · 2026-05-02 00:21:28 +00:00 · 2026-05-01 22:33:22 +00:00 · 2026-05-01 22:17:17 +00:00
233 changed files with 31934 additions and 2483 deletions
@@ -0,0 +1,31 @@
+# Project-wide cargo configuration.
+#
+# Routes every rustc invocation through `sccache` so cold rebuilds and
+# fresh checkouts (CI, new dev box, after a `cargo clean`) replay
+# previously-compiled crates from a local on-disk cache rather than
+# recompiling them. Warm incremental builds still go through cargo's
+# own `target/` cache, which dominates locally — sccache buys you the
+# big wins on cold paths.
+#
+# Requires sccache on PATH. Install it once per machine:
+#
+#   Arch     :  pacman -S sccache
+#   macOS    :  brew install sccache
+#   Cargo    :  cargo install sccache --locked
+#
+# Without sccache the build fails with "rustc-wrapper not found". To
+# bypass this config without editing the file, prepend
+# `RUSTC_WRAPPER= ` (empty value) to your cargo command:
+#
+#   RUSTC_WRAPPER= cargo build
+#
+[build]
+rustc-wrapper = "sccache"
+
+# Project-local cache so the shared dev box (or a Docker volume) keeps
+# the artefacts isolated per checkout instead of mixing them in
+# `~/.cache/sccache`. Set with `force = false` so a developer-set
+# `SCCACHE_DIR` in their shell wins — important because the sccache
+# daemon, once started, sticks with whichever directory it saw first.
+[env]
+SCCACHE_DIR = { value = ".sccache-cache", relative = true, force = false }
@@ -1,4 +1,5 @@
 /target
+/.sccache-cache
 *.db
 *.db-shm
 *.db-wal
@@ -51,6 +51,7 @@ Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, tar
 - **No panics in game logic.** Every state transition returns `Result<_, MoveError>`. Panics are only acceptable in startup/configuration code.
 - **One language, one repo.** The game client, sync client, shared types, and sync server are all Rust crates in a single Cargo workspace.
 - **Plugin-based Bevy architecture.** Each major feature is a Bevy `Plugin`. Systems are small and single-purpose. Cross-system communication uses Bevy `Event`s.
+- **UI-first interaction.** Every player-triggered action — new game, undo, draw, pause, open stats / settings / help / profile / leaderboard, etc. — must be reachable from a visible UI control. Keyboard shortcuts exist only as optional accelerators for power users; they are never the sole entry point. A player using only mouse or touch must be able to perform every action. New gameplay features ship with the UI control alongside the system that backs it.

 ---

@@ -67,11 +68,11 @@ solitaire_quest/
 ├── Dockerfile                  # Multi-stage server build
 ├── docker-compose.yml          # Server + Caddy reverse proxy
 │
-├── assets/                     # Assets embedded at compile time via include_bytes!()
+├── assets/                     # Loaded at runtime via AssetServer (audio is embedded via include_bytes!())
 │   ├── cards/
-│   │   ├── faces/{rank}_{suit}.png  # 52 individual card faces (120×168, generated by solitaire_assetgen)
-│   │   └── backs/back_0.png – back_4.png    # placeholder patterns
-│   ├── backgrounds/bg_0.png – bg_4.png      # placeholder textures
+│   │   ├── faces/{RANK}{SUIT}.png   # 52 card faces — rendered from hayeah/playing-cards-assets SVGs (MIT)
+│   │   └── backs/back_0.png – back_4.png    # back_0 = generated default back; back_1–4 are generated patterns
+│   ├── backgrounds/bg_0.png – bg_4.png      # generated textures
 │   ├── fonts/main.ttf          # FiraMono-Medium (170K, OFL)
 │   └── audio/
 │       ├── card_deal.wav
@@ -132,7 +133,7 @@ Owns:
 - `SyncProvider` trait — implemented by `SolitaireServerClient`

 ### `solitaire_engine`
-**Dependencies:** `bevy`, `bevy_kira_audio`, `solitaire_core`, `solitaire_data`.
+**Dependencies:** `bevy`, `kira`, `solitaire_core`, `solitaire_data`.

 All Bevy-specific code. Structured as a collection of Plugins that `solitaire_app` registers.

@@ -144,7 +145,7 @@ Owns:
 - All Bevy UI screens (Home, Stats, Achievements, Settings, Profile)
 - Audio playback systems
 - Sync status display
- Card, background, and font asset loading (embedded via `include_bytes!()` — no `AssetServer` dependency)
+- Card, background, and font asset loading via Bevy `AssetServer` (audio is the lone exception — embedded via `include_bytes!()` in `audio_plugin.rs`)

 ### `solitaire_server`
 **Dependencies:** `solitaire_sync`, `axum`, `sqlx`, `jsonwebtoken`, `bcrypt`, `tower-governor`, `tracing`, `tokio`, `dotenvy`.
@@ -235,20 +236,22 @@ Done

 ### Bevy Plugins

-| Plugin | Key | Responsibility |
+The "Shortcut" column lists optional keyboard accelerators. Every action in this table must also be reachable from a visible UI control (button, menu item, on-screen affordance) per the UI-first design principle in §1; the shortcut is a power-user convenience, not the sole entry point.
+
+| Plugin | Shortcut | Responsibility |
 |---|---|---|
 | `CardPlugin` | — | Card entity spawning, sprite management, drag-and-drop |
 | `TablePlugin` | — | Pile markers, background, layout calculation |
-| `FontPlugin` | — | Embeds FiraMono-Medium font at compile time; exposes `FontResource` handle |
+| `FontPlugin` | — | Loads FiraMono-Medium via `AssetServer` at startup; exposes `FontResource` handle |
 | `AnimationPlugin` | — | Slide, flip, win cascade, toast animations |
 | `FeedbackAnimPlugin` | — | Shake, settle, and deal-stagger animations |
 | `AutoCompletePlugin` | Enter | Executes auto-complete when the HUD badge is lit |
-| `AudioPlugin` | — | Sound effect and music playback via bevy_kira_audio |
+| `AudioPlugin` | — | Sound effect and music playback via kira |
 | `InputPlugin` | — | Keyboard and mouse input routing |
 | `CursorPlugin` | — | Custom cursor sprite during drag |
 | `SelectionPlugin` | — | Keyboard-driven card selection |
 | `GamePlugin` | N | Core game state resource, new-game flow, win/game-over overlays |
-| `HudPlugin` | — | Score, move counter, timer, auto-complete badge |
+| `HudPlugin` | — | Score, move counter, timer, auto-complete badge, and the top-right action button bar (Undo / Pause / Help / New Game). Each button fires the same request event the corresponding hotkey does. |
 | `StatsPlugin` | S | Stats overlay and persistence |
 | `ProgressPlugin` | — | XP/level system, persistence |
 | `AchievementPlugin` | A | Unlock evaluation, toast events, persistence |
@@ -296,7 +299,7 @@ struct CardImageSet {
    backs: [Handle<Image>; 5],       // indexed by selected_card_back setting
 }

-// Project-wide font handle (FiraMono-Medium embedded at compile time)
+// Project-wide font handle (FiraMono-Medium loaded via AssetServer at startup)
 struct FontResource(Handle<Font>);

 // Pre-loaded background PNG handles
@@ -751,7 +754,7 @@ Levels 11+:   level = 10 + floor((total_xp - 5000) / 1000)

 ## 13. Audio System

-Audio uses `bevy_kira_audio`. All sound files are `.wav`.
+Audio uses `kira`. All sound files are `.wav`.

 | File | Trigger |
 |---|---|
@@ -762,7 +765,7 @@ Audio uses `bevy_kira_audio`. All sound files are `.wav`.
 | `win_fanfare.wav` | Game won |
 | `ambient_loop.wav` | Looping background music |

-Volume is controlled by two independent sliders in Settings (`sfx_volume`, `music_volume`), each stored in `Settings` and applied as `bevy_kira_audio` channel volumes.
+Volume is controlled by two independent sliders in Settings (`sfx_volume`, `music_volume`), each stored in `Settings` and applied as `kira` channel volumes.

 Audio systems listen for Bevy events and never block the game thread.

@@ -772,11 +775,13 @@ Audio systems listen for Bevy events and never block the game thread.

 ### Rendering approach

-Cards are Bevy `Sprite` entities with `Handle<Image>` from `CardImageSet`. Face-up cards use one of 52 individual face PNGs selected by `faces[suit][rank]` — rank and suit are baked into each image and no `Text2d` overlay is spawned. Face-down cards use `backs/back_N.png` indexed by `settings.selected_card_back`. `Text2d` labels are only used as a fallback when `CardImageSet` is absent (e.g. tests with `MinimalPlugins`). `CardImageSet` is populated at startup from `include_bytes!()` — no `AssetServer`.
+Cards are Bevy `Sprite` entities with `Handle<Image>` from `CardImageSet`. Face-up cards use one of 52 individual face PNGs selected by `faces[suit][rank]` — rank and suit are baked into each image and no `Text2d` overlay is spawned. Face-down cards use `backs/back_N.png` indexed by `settings.selected_card_back`. `Text2d` labels are only used as a fallback when `CardImageSet` is absent (e.g. tests with `MinimalPlugins`). `CardImageSet` is populated at startup by `card_plugin::load_card_images` via `AssetServer::load()`.

-Backgrounds are Bevy `Sprite` entities with `Handle<Image>` from `BackgroundImageSet`. `BackgroundImageSet` is populated at startup from `include_bytes!()`.
+Backgrounds are Bevy `Sprite` entities with `Handle<Image>` from `BackgroundImageSet`. `BackgroundImageSet` is populated at startup by `table_plugin::load_background_images` via `AssetServer::load()`.

-The font `FiraMono-Medium` is embedded via `include_bytes!()` at startup by `FontPlugin` and exposed as `FontResource` for use by all UI and text systems.
+The font `FiraMono-Medium` is loaded via `AssetServer::load("fonts/main.ttf")` at startup by `FontPlugin` and exposed as `FontResource` for use by all UI and text systems.
+
+All three loaders take `Option<Res<AssetServer>>` so they degrade cleanly under `MinimalPlugins` in tests: when the server is absent, `CardImageSet`/`BackgroundImageSet` are inserted with empty handle slots and the plugins fall back to `Text2d` rank+suit overlays and solid-colour board backgrounds. The `assets/` directory must ship alongside the binary.

 The `assets/` directory layout:

@@ -1004,5 +1009,7 @@ Using `axum::test` and an in-memory SQLite database:
 | `SyncProvider` trait, not `SyncBackend` match arms | `SyncPlugin` stays backend-agnostic and testable; new backends can be added without touching the plugin | 2026-04-20 |
 | Dropped WebDAV backend | Redundant once the self-hosted server exists; removing it reduces surface area and simplifies settings UI | 2026-04-20 |
 | Dropped GPGS backend | Redundant with the self-hosted server; adds JNI complexity for no user-visible benefit on the target platforms | 2026-04-28 |
-| PNG assets embedded via `include_bytes!()` | Using `Image::from_buffer()` in startup systems rather than `AssetServer::load()` keeps the binary self-contained and eliminates runtime file-not-found errors | 2026-04-29 |
-| FiraMono-Medium font embedded via `include_bytes!()` | Exposed through `FontResource`; avoids runtime font loading errors on headless systems and ensures consistent text rendering across all platforms | 2026-04-29 |
+| Card, background, and font assets loaded via `AssetServer` | Reverses the earlier embed-via-`include_bytes!()` decision: PNGs and TTFs are loaded at runtime so artwork can be swapped (e.g. alternate card backs, themed backgrounds) without a recompile, and binary size stays small. Loaders take `Option<Res<AssetServer>>` and fall back gracefully under `MinimalPlugins`. The `assets/` directory must ship alongside the binary. | 2026-04-29 |
+| Audio assets remain embedded via `include_bytes!()` | Audio files are small, change rarely, and the embedded path eliminates a class of runtime-load errors during gameplay; the asset-pipeline reversal does not extend to audio | 2026-04-29 |
+| Card art swapped from xCards (LGPL-3.0) to hayeah/playing-cards-assets (MIT) | Public-release readiness. The previous xCards art carried LGPL relinking obligations that complicate a single-binary distribution; hayeah's set derives from the public-domain `vector-playing-cards` line-art and is permissively MIT-licensed. CREDITS.md license summary collapsed to MIT + OFL-1.1. The default card back is original work in this project's midnight-purple palette. | 2026-05-01 |
+| Runtime SVG card-theme system (`CARD_PLAN.md`) | User-supplied themes need to ship SVG sources so they can rasterise at any resolution on the player's hardware; baking PNGs at build time only would lock theme installation to the developer. The pipeline (usvg → resvg → tiny-skia) rasterises once per (theme, target size) at load time and caches the resulting `Image`, so the runtime cost is paid once, not per frame. The bundled default theme ships via `embedded://`; user themes via `themes://` rooted at `user_theme_dir()`. | 2026-05-01 |
@@ -47,7 +47,9 @@ cargo clippy -p solitaire_core -- -D warnings

 - `solitaire_core` and `solitaire_sync` must never gain Bevy or network dependencies.
 - No `unwrap()` or `panic!()` in game logic. All state transitions return `Result<_, MoveError>`.
- Audio assets are embedded at compile time using `include_bytes!()` in `audio_plugin.rs`. Cards and backgrounds are rendered procedurally (colored `Sprite` entities + text) — no image files are used and no `AssetServer` is needed.
+- Audio assets are embedded at compile time using `include_bytes!()` in `audio_plugin.rs`.
+- Card faces (52 PNGs in `assets/cards/faces/`), card backs (`assets/cards/backs/back_N.png`), board backgrounds (`assets/backgrounds/bg_N.png`), and the UI font (`assets/fonts/main.ttf`) are loaded at runtime via `AssetServer::load()` and stored as `Handle<Image>`/`Handle<Font>` in the `CardImageSet`, `BackgroundImageSet`, and `FontResource` resources. The `assets/` directory must ship alongside the binary.
+- Asset-loading systems take `Option<Res<AssetServer>>` so they degrade cleanly under `MinimalPlugins` (tests). When `CardImageSet` is absent, `card_plugin` falls back to a `Text2d` rank+suit overlay; when `BackgroundImageSet` is absent, the board falls back to a solid colour.
 - Atomic file writes only: write to `filename.json.tmp`, then `rename()`.
 - Passwords and tokens are stored in the OS keychain via the `keyring` crate — never in plaintext files or logs.
 - Sync runs on `AsyncComputeTaskPool` — never block the Bevy main thread.
@@ -75,6 +77,7 @@ cargo clippy -p solitaire_core -- -D warnings
 - Resources own shared state. Events communicate between systems. Components own per-entity data.
 - All UI screens are built with Bevy UI (`bevy::ui`). Never mix UI layout and game logic in the same system.
 - Layout is recomputed on `WindowResized` — never assume a fixed window size.
+- **UI-first.** Every player-triggered action (new game, undo, draw, pause, open stats / settings / help / profile / leaderboard, switch mode, etc.) must be reachable from a visible UI control. Keyboard shortcuts are optional accelerators — never the sole entry point. New gameplay features ship with the UI control alongside the system that backs it; do not merge a feature that is keyboard-only.

 ---

@@ -0,0 +1,112 @@
+# Credits
+
+Solitaire Quest is MIT-licensed (see [LICENSE](LICENSE)). It is built on top of
+the work of many open-source projects and a small handful of third-party
+assets. This file lists every component that ships in the binary or in the
+`assets/` directory.
+
+---
+
+## Code & Framework
+
+| Component | License | Role |
+|---|---|---|
+| [Bevy 0.18](https://bevyengine.org/) | MIT OR Apache-2.0 | Game engine, ECS, rendering, UI |
+| [kira 0.12](https://crates.io/crates/kira) | MIT OR Apache-2.0 | Audio playback (mixer, sub-tracks, looping ambient) |
+| [serde](https://crates.io/crates/serde) / [serde_json](https://crates.io/crates/serde_json) | MIT OR Apache-2.0 | Serialization for save files and the sync API |
+| [tokio](https://crates.io/crates/tokio) | MIT | Async runtime for the sync client and server |
+| [axum 0.8](https://crates.io/crates/axum) | MIT | HTTP framework for the self-hosted sync server |
+| [sqlx 0.8](https://crates.io/crates/sqlx) | MIT OR Apache-2.0 | Compile-time-checked SQLite access on the server |
+| [reqwest 0.13](https://crates.io/crates/reqwest) | MIT OR Apache-2.0 | HTTP client for the sync provider |
+| [jsonwebtoken 10](https://crates.io/crates/jsonwebtoken) | MIT | JWT issuance and validation |
+| [bcrypt 0.19](https://crates.io/crates/bcrypt) | MIT | Password hashing on the server |
+| [keyring 4](https://crates.io/crates/keyring) | MIT OR Apache-2.0 | OS keychain integration for credential storage |
+| [tower-governor 0.8](https://crates.io/crates/tower-governor) | MIT | Rate limiting on `/api/auth/*` |
+| [chrono](https://crates.io/crates/chrono) | MIT OR Apache-2.0 | Date / time handling |
+| [uuid](https://crates.io/crates/uuid) | MIT OR Apache-2.0 | User and session identifiers |
+| [thiserror](https://crates.io/crates/thiserror) | MIT OR Apache-2.0 | Error type derive |
+| [rand 0.9](https://crates.io/crates/rand) | MIT OR Apache-2.0 | Seeded shuffler in `solitaire_core` |
+| [png 0.17](https://crates.io/crates/png) | MIT OR Apache-2.0 | PNG encoder used by `solitaire_assetgen` |
+| [ab_glyph 0.2](https://crates.io/crates/ab_glyph) | Apache-2.0 | Glyph rasterization for generated card art |
+
+The full transitive dependency tree (several hundred crates) is captured in
+`Cargo.lock` and reachable via `cargo tree`. Every crate brought in is
+MIT, Apache-2.0, BSD-style, or a dual-licensed combination thereof — no
+copyleft code is statically linked into the game binary.
+
+---
+
+## Assets
+
+### Card artwork
+
+| File(s) | Source | License |
+|---|---|---|
+| `solitaire_engine/assets/themes/default/{suit}_{rank}.svg` (52 SVGs) | [hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets) | MIT |
+| `solitaire_engine/assets/themes/default/back.svg` | Original — Solitaire Quest | MIT (this project) |
+| `assets/cards/faces/{RANK}{SUIT}.png` (52 PNGs) | Pre-rendered from the same `playing-cards-assets` SVGs | MIT (passed through from hayeah) |
+| `assets/cards/backs/back_0.png` – `back_4.png` | Original — generated by `solitaire_assetgen::gen_art` | MIT (this project) |
+
+The face SVGs come from Howard Yeh's `playing-cards-assets` repository, which
+is itself derived from the public-domain `vector-playing-cards` Google Code
+project. The art is redistributed under the MIT license — see the upstream
+repository for the full notice. The files ship unmodified in the bundled
+default theme; user-supplied themes can override them per-installation
+through the runtime SVG theming system documented in `CARD_PLAN.md`.
+
+The default card back is original work by this project, midnight-purple
+themed to match the rest of the UI palette.
+
+### Backgrounds
+
+| File(s) | Source | License |
+|---|---|---|
+| `assets/backgrounds/bg_0.png` – `bg_4.png` | Original — generated by `solitaire_assetgen::gen_art` | MIT (this project) |
+
+### Typography
+
+| File | Source | License |
+|---|---|---|
+| `assets/fonts/main.ttf` (FiraMono-Medium) | [mozilla/Fira](https://github.com/mozilla/Fira) | SIL Open Font License 1.1 |
+
+The OFL permits redistribution and embedding in software so long as the font
+file itself is not sold standalone. The file ships unmodified.
+
+### Audio
+
+All six WAV files in `assets/audio/` are **original work** — there are no
+third-party audio samples in this project. They are synthesized
+programmatically by `solitaire_assetgen/src/bin/gen_sfx.rs`, which writes
+44.1 kHz mono 16-bit PCM WAVs using a hand-rolled WAV writer (no `hound` or
+`dasp` dependency). The synthesis stack is entirely additive: sine /
+square waves, layered harmonics, deterministic LCG noise, AR envelopes,
+and a slow LFO for the ambient track.
+
+| File | Synthesis approach |
+|---|---|
+| `card_deal.wav` | Filtered LCG noise with a sweeping low-pass cutoff for a "whoosh" |
+| `card_flip.wav` | High-passed LCG noise under a fast AR envelope |
+| `card_place.wav` | 120 Hz sine body + filtered noise click |
+| `card_invalid.wav` | Two dissonant square tones (196 Hz + 207.65 Hz) beating against each other |
+| `win_fanfare.wav` | C-major arpeggio (C5 / E5 / G5 / C6) with sine + 2nd harmonic |
+| `ambient_loop.wav` | 55 Hz fundamental with 2nd and 3rd harmonics, modulated by a 0.2 Hz LFO; loop length is chosen so the tone and LFO both complete an integer number of cycles for seamless looping |
+
+Audio files are MIT-licensed alongside the rest of this project.
+
+---
+
+## License Summary
+
+- **Project code:** MIT — see [LICENSE](LICENSE).
+- **Card face artwork (52 SVGs from hayeah/playing-cards-assets, plus the
+  pre-rendered PNGs in `assets/cards/faces/`):** MIT, redistributed
+  unmodified. The original `vector-playing-cards` line art is itself
+  public domain.
+- **FiraMono-Medium font:** SIL Open Font License 1.1, redistributed unmodified.
+- **All other assets** (backgrounds, the default `back.svg`, generated card
+  backs, every audio file) are original work covered by this project's MIT
+  license.
+
+If you redistribute Solitaire Quest, you must ship this `CREDITS.md` and the
+`LICENSE` file alongside the binary so the MIT (project + hayeah card art)
+and OFL (FiraMono) notices remain visible to end users.
@@ -2429,6 +2429,12 @@ dependencies = [
 "unicode-width",
 ]

+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
 [[package]]
 name = "colorchoice"
 version = "1.0.5"
@@ -2950,6 +2956,12 @@ version = "2.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"

+[[package]]
+name = "data-url"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be1e0bca6c3637f992fc1cc7cbc52a78c1ef6db076dbf1059c4323d6a2048376"
+
 [[package]]
 name = "datasketches"
 version = "0.2.0"
@@ -3477,8 +3489,15 @@ checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
 dependencies = [
 "crc32fast",
 "miniz_oxide",
+ "zlib-rs",
 ]

+[[package]]
+name = "float-cmp"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
+
 [[package]]
 name = "flume"
 version = "0.11.1"
@@ -3532,7 +3551,7 @@ version = "0.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbc773e24e02d4ddd8395fd30dc147524273a83e54e0f312d986ea30de5f5646"
 dependencies = [
- "roxmltree",
+ "roxmltree 0.20.0",
 ]

 [[package]]
@@ -3851,6 +3870,16 @@ dependencies = [
 "polyval",
 ]

+[[package]]
+name = "gif"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee8cfcc411d9adbbaba82fb72661cc1bcca13e8bba98b364e62b2dba8f960159"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
 [[package]]
 name = "gilrs"
 version = "0.11.1"
@@ -4529,6 +4558,22 @@ dependencies = [
 "png 0.18.1",
 ]

+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
+[[package]]
+name = "imagesize"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09e54e57b4c48b40f7aec75635392b12b3421fa26fe8b4332e63138ed278459c"
+
 [[package]]
 name = "indexmap"
 version = "2.14.0"
@@ -4856,6 +4901,17 @@ dependencies = [
 "bitflags 2.11.1",
 ]

+[[package]]
+name = "kurbo"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7564e90fe3c0d5771e1f0bc95322b21baaeaa0d9213fa6a0b61c99f8b17b3bfb"
+dependencies = [
+ "arrayvec",
+ "euclid",
+ "smallvec",
+]
+
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -6011,15 +6067,6 @@ dependencies = [
 "libredox",
 ]

-[[package]]
-name = "ordered-float"
-version = "4.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7bb71e1b3fa6ca1c61f383464aaf2bb0e2f8e772a1f01d486832464de363b951"
-dependencies = [
- "num-traits",
-]
-
 [[package]]
 name = "ordered-float"
 version = "5.3.0"
@@ -6165,6 +6212,12 @@ dependencies = [
 "serde_derive",
 ]

+[[package]]
+name = "pico-args"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5be167a7af36ee22fe3115051bc51f6e6c7054c9348e28deb4f49bd6f705a315"
+
 [[package]]
 name = "pin-project"
 version = "1.1.11"
@@ -6428,6 +6481,12 @@ dependencies = [
 "winapi",
 ]

+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quick-xml"
 version = "0.39.2"
@@ -6798,6 +6857,23 @@ dependencies = [
 "web-sys",
 ]

+[[package]]
+name = "resvg"
+version = "0.47.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9be183ad6a216aa96f33e4c8033b0988b8b3ea6fd2359d19af5bac4643fd8e81"
+dependencies = [
+ "gif",
+ "image-webp",
+ "log",
+ "pico-args",
+ "rgb",
+ "svgtypes",
+ "tiny-skia 0.12.0",
+ "usvg",
+ "zune-jpeg",
+]
+
 [[package]]
 name = "rfc6979"
 version = "0.4.0"
@@ -6808,6 +6884,15 @@ dependencies = [
 "subtle",
 ]

+[[package]]
+name = "rgb"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -6862,6 +6947,15 @@ version = "0.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6c20b6793b5c2fa6553b250154b78d6d0db37e72700ae35fad9387a46f487c97"

+[[package]]
+name = "roxmltree"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1964b10c76125c36f8afe190065a4bf9a87bf324842c05701330bba9f1cacbb"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "rpassword"
 version = "7.5.0"
@@ -7068,6 +7162,24 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"

+[[package]]
+name = "rustybuzz"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd3c7c96f8a08ee34eff8857b11b49b07d71d1c3f4e88f8a88d4c9e9f90b1702"
+dependencies = [
+ "bitflags 2.11.1",
+ "bytemuck",
+ "core_maths",
+ "log",
+ "smallvec",
+ "ttf-parser",
+ "unicode-bidi-mirroring",
+ "unicode-ccc",
+ "unicode-properties",
+ "unicode-script",
+]
+
 [[package]]
 name = "ruzstd"
 version = "0.8.2"
@@ -7123,7 +7235,7 @@ dependencies = [
 "log",
 "memmap2",
 "smithay-client-toolkit",
- "tiny-skia",
+ "tiny-skia 0.11.4",
 ]

 [[package]]
@@ -7382,6 +7494,15 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"

+[[package]]
+name = "simplecss"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a9c6883ca9c3c7c90e888de77b7a5c849c779d25d74a1269b0218b14e8b136c"
+dependencies = [
+ "log",
+]
+
 [[package]]
 name = "simsimd"
 version = "6.5.16"
@@ -7522,7 +7643,6 @@ dependencies = [
 name = "solitaire_core"
 version = "0.1.0"
 dependencies = [
- "chrono",
 "rand 0.9.4",
 "serde",
 "thiserror 2.0.18",
@@ -7533,16 +7653,21 @@ name = "solitaire_data"
 version = "0.1.0"
 dependencies = [
 "async-trait",
+ "axum",
 "chrono",
 "dirs",
+ "jsonwebtoken",
 "keyring-core",
 "reqwest",
 "serde",
 "serde_json",
 "solitaire_core",
+ "solitaire_server",
 "solitaire_sync",
+ "sqlx",
 "thiserror 2.0.18",
 "tokio",
+ "uuid",
 ]

 [[package]]
@@ -7552,12 +7677,21 @@ dependencies = [
 "async-trait",
 "bevy",
 "chrono",
+ "dirs",
 "kira",
+ "resvg",
+ "ron",
+ "serde",
 "solitaire_core",
 "solitaire_data",
 "solitaire_sync",
+ "tempfile",
+ "thiserror 2.0.18",
+ "tiny-skia 0.12.0",
 "tokio",
+ "usvg",
 "uuid",
+ "zip",
 ]

 [[package]]
@@ -7588,7 +7722,6 @@ version = "0.1.0"
 dependencies = [
 "chrono",
 "serde",
- "serde_json",
 "thiserror 2.0.18",
 "uuid",
 ]
@@ -7855,6 +7988,9 @@ name = "strict-num"
 version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6637bab7722d379c8b41ba849228d680cc12d0a45ba1fa2b48f2a30577a06731"
+dependencies = [
+ "float-cmp",
+]

 [[package]]
 name = "stringprep"
@@ -7907,6 +8043,16 @@ version = "0.4.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0193cc4331cfd2f3d2011ef287590868599a2f33c3e69bc22c1a3d3acf9e02fb"

+[[package]]
+name = "svgtypes"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "695b5790b3131dafa99b3bbfd25a216edb3d216dad9ca208d4657bfb8f2abc3d"
+dependencies = [
+ "kurbo",
+ "siphasher",
+]
+
 [[package]]
 name = "swash"
 version = "0.2.7"
@@ -8221,7 +8367,7 @@ checksum = "dfadb8526b6da90704feb293b0701a6aae62ea14983143344be2dc5ce30f1d82"
 dependencies = [
 "fnv",
 "nom",
- "ordered-float 5.3.0",
+ "ordered-float",
 "serde",
 "serde_json",
 ]
@@ -8378,7 +8524,22 @@ dependencies = [
 "bytemuck",
 "cfg-if",
 "log",
- "tiny-skia-path",
+ "tiny-skia-path 0.11.4",
+]
+
+[[package]]
+name = "tiny-skia"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47ffee5eaaf5527f630fb0e356b90ebdec84d5d18d937c5e440350f88c5a91ea"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "bytemuck",
+ "cfg-if",
+ "log",
+ "png 0.18.1",
+ "tiny-skia-path 0.12.0",
 ]

 [[package]]
@@ -8392,6 +8553,17 @@ dependencies = [
 "strict-num",
 ]

+[[package]]
+name = "tiny-skia-path"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edca365c3faccca67d06593c5980fa6c57687de727a03131735bb85f01fdeeb9"
+dependencies = [
+ "arrayref",
+ "bytemuck",
+ "strict-num",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.3"
@@ -8942,6 +9114,12 @@ dependencies = [
 "rand 0.9.4",
 ]

+[[package]]
+name = "typed-path"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
+
 [[package]]
 name = "typeid"
 version = "1.0.3"
@@ -9010,6 +9188,18 @@ version = "0.3.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"

+[[package]]
+name = "unicode-bidi-mirroring"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5dfa6e8c60bb66d49db113e0125ee8711b7647b5579dc7f5f19c42357ed039fe"
+
+[[package]]
+name = "unicode-ccc"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce61d488bcdc9bc8b5d1772c404828b17fc481c0a582b5581e95fb233aef503e"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -9049,6 +9239,12 @@ version = "1.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c"

+[[package]]
+name = "unicode-vo"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1d386ff53b415b7fe27b50bb44679e2cc4660272694b7b6f3326d8480823a94"
+
 [[package]]
 name = "unicode-width"
 version = "0.1.14"
@@ -9089,6 +9285,34 @@ dependencies = [
 "serde",
 ]

+[[package]]
+name = "usvg"
+version = "0.47.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d46cf96c5f498d36b7a9693bc6a7075c0bb9303189d61b2249b0dc3d309c07de"
+dependencies = [
+ "base64",
+ "data-url",
+ "flate2",
+ "fontdb",
+ "imagesize",
+ "kurbo",
+ "log",
+ "pico-args",
+ "roxmltree 0.21.1",
+ "rustybuzz",
+ "simplecss",
+ "siphasher",
+ "strict-num",
+ "svgtypes",
+ "tiny-skia-path 0.12.0",
+ "ttf-parser",
+ "unicode-bidi",
+ "unicode-script",
+ "unicode-vo",
+ "xmlwriter",
+]
+
 [[package]]
 name = "utf8-ranges"
 version = "1.0.5"
@@ -9448,6 +9672,12 @@ dependencies = [
 "rustls-pki-types",
 ]

+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
 [[package]]
 name = "wgpu"
 version = "27.0.1"
@@ -9566,7 +9796,7 @@ dependencies = [
 "ndk-sys 0.6.0+11769913",
 "objc",
 "once_cell",
- "ordered-float 4.6.0",
+ "ordered-float",
 "parking_lot",
 "portable-atomic",
 "portable-atomic-util",
@@ -10495,6 +10725,12 @@ version = "0.8.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ae8337f8a065cfc972643663ea4279e04e7256de865aa66fe25cec5fb912d3f"

+[[package]]
+name = "xmlwriter"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec7a2a501ed189703dba8b08142f057e887dfc4b2cc4db2d343ac6376ba3e0b9"
+
 [[package]]
 name = "yazi"
 version = "0.2.1"
@@ -10696,12 +10932,44 @@ dependencies = [
 "syn",
 ]

+[[package]]
+name = "zip"
+version = "8.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"
+dependencies = [
+ "crc32fast",
+ "flate2",
+ "indexmap",
+ "memchr",
+ "typed-path",
+ "zopfli",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3be3d40e40a133f9c916ee3f9f4fa2d9d63435b5fbe1bfc6d9dae0aa0ada1513"
+
 [[package]]
 name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"

+[[package]]
+name = "zopfli"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
+dependencies = [
+ "bumpalo",
+ "crc32fast",
+ "log",
+ "simd-adler32",
+]
+
 [[package]]
 name = "zstd"
 version = "0.13.3"
@@ -10730,6 +10998,21 @@ dependencies = [
 "pkg-config",
 ]

+[[package]]
+name = "zune-core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
+
 [[package]]
 name = "zvariant"
 version = "5.10.1"
@@ -38,6 +38,30 @@ solitaire_engine = { path = "solitaire_engine" }
 bevy = "0.18"
 kira = "0.12"

+# SVG rasterisation pipeline for the runtime card-theme system.
+# usvg parses + simplifies; resvg renders to a tiny-skia Pixmap;
+# tiny-skia provides the CPU rasteriser. All three are maintained
+# together by the resvg-rs project and version in lockstep.
+usvg      = "0.47"
+resvg     = "0.47"
+tiny-skia = "0.12"
+
+# Theme manifest format. RON keeps the file human-editable while
+# preserving Rust-style structures the importer can validate.
+ron = "0.12"
+
+# Importer-only: reads user-supplied theme zip archives, validates
+# their contents, and unpacks them into the user themes directory.
+# Default features are disabled to keep the dependency footprint small;
+# only `deflate` is needed because the importer rejects other
+# compression methods anyway (see Phase 7 spec).
+zip = { version = "8.6", default-features = false, features = ["deflate"] }
+
+# Importer-only test dependency: tests build zip archives in a
+# scratch directory so they don't pollute the real user themes path
+# on the developer's machine.
+tempfile = "3.27"
+
 axum               = "0.8"
 sqlx               = { version = "0.8", features = ["runtime-tokio-rustls", "sqlite", "macros", "migrate"] }
 jsonwebtoken       = { version = "10", default-features = false, features = ["rust_crypto"] }
@@ -68,6 +68,16 @@ cargo test -p solitaire_core -p solitaire_sync -p solitaire_data -p solitaire_se
 cargo clippy --workspace -- -D warnings
 ```

+## Credits
+
+Built on [Bevy](https://bevyengine.org/) and the wider Rust ecosystem (Tokio,
+Axum, sqlx, Serde, kira, and many more). Card faces come from
+[hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets)
+(MIT, derived from the public-domain `vector-playing-cards` library); the
+default card back is original work; the UI font is FiraMono-Medium (OFL).
+All audio is synthesized programmatically by this project. See
+[CREDITS.md](CREDITS.md) for the full list and license details.
+
 ## License

 MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,110 @@
+# Solitaire Quest — UX Overhaul Session Handoff
+
+**Last updated:** 2026-05-02 (session 7) — UX iteration round complete: every item from session 6's UX punch list has shipped, plus a font-fallback fix surfaced by a second-machine smoke test. Six commits on top of session 6's `c4970b1`. Direction now opens for the next round — release prep or another UX pass, the player's call.
+
+## Status at pause
+
+- **HEAD:** `655dfde`. Local master is **3 commits ahead** of `origin/master` (`f6c9166`, `f712b89`, `655dfde` unpushed; `fdb6c2e` and `95df542` already pushed).
+- **Working tree:** clean. (`CARD_PLAN.md` is untracked but intentionally so — it's a plan doc, not source.)
+- **Build:** `cargo clippy --workspace --all-targets -- -D warnings` clean.
+- **Tests:** **982 passed / 0 failed** across the workspace (+20 from session 6's 962 baseline).
+- **Tags on origin:** `v0.9.0`, `v0.10.0`. Stale local-only `v0.1.0` is still safe to `git tag -d v0.1.0`.
+
+## Where we are
+
+Session 6's UX punch list was four items. All four shipped today, plus an unrelated font-fallback fix from a second-machine smoke test.
+
+The card-theme system, HUD restructure, modal scaffold, and the four big UX feel items (foundations, drop shadows, drop highlights, stock badge) are all in. Direction is open — the deferred release-prep items (`v0.11.0` cut, README/CHANGELOG refresh, desktop packaging) are still on the table, and a fresh round of UX iteration is also available.
+
+### Design direction (unchanged)
+
+- **Tone:** Balatro — chunky readable type, theatrical hierarchy, satisfying micro-interactions.
+- **Palette:** Midnight Purple base + Balatro yellow primary + warm magenta secondary.
+- See `~/.claude/projects/-home-manage-Rusty-Solitare/memory/project_ux_overhaul_2026-04.md` (auto-memory; on a different machine, recreate this fresh from the README + ARCHITECTURE.md).
+
+### Canonical remote
+
+`github.com/funman300/Rusty_Solitaire` is the canonical repo. Always push there. (Earlier sessions used `Rusty_Solitare` — single-i typo — as the repo name; the rename to `Rusty_Solitaire` happened in session 7. Local clone directories may still be named `Rusty_Solitare`; that's just a directory name and works fine.)
+
+## Session 7 (shipped 2026-05-02)
+
+| Area | Commit | What landed |
+|---|---|---|
+| Font fallback | `fdb6c2e` | `shared_fontdb` now `include_bytes!()`s `assets/fonts/main.ttf` (FiraMono) and pins every CSS generic to `"Fira Mono"` so unmatched named families on minimal Linux installs / fresh Wayland sessions / chroots don't drop card rank/suit text. Surfaced when a second-machine pull rendered cards without glyphs. |
+| Unlock foundations | `95df542` | `PileType::Foundation(Suit)` → `Foundation(u8)` (slot 0..3). `Pile::claimed_suit()` derives the claim from the bottom card — no separate field, no claim-stuck-after-undo class of bugs. `can_place_on_foundation` drops its suit parameter. `next_auto_complete_move` prefers a slot whose claimed suit matches the candidate before falling back to the first empty slot for an Ace. Empty foundation markers render as plain placeholders (no "C/D/H/S"). HUD selection label and hint toast read `claimed_suit()` and fall through to "Foundation N" / "move to foundation" when the slot is empty. Save-format invalidation: `GameState.schema_version` bumped 1 → 2; old `game_state.json` files silently fall through to "fresh game on launch." Stats / progress / achievements / settings live in separate files and are unaffected. 9 new tests. |
+| Drop overlay | `f6c9166` | The pre-existing `update_drop_highlights` system tinted `PileMarker` sprites green for valid drops, but markers were occluded by stacked cards — invisible during real play. New `update_drop_target_overlays` spawns a soft-fill + 3 px outlined box ABOVE cards for every legal target (full fanned column for tableaux, card-sized for foundations / empty tableaux). `Z_DROP_OVERLAY = 50` sits above static cards but below `DRAG_Z = 500` so the dragged card never gets occluded. Reuses `STATE_SUCCESS` hue. The original marker-tint system is untouched. 3 new tests. |
+| Drop shadows | `f712b89` | Each `CardEntity` spawns a `CardShadow` child sprite — neutral black at 25 % alpha, sized `card_size + 4 px`, offset `(2, -3)`, local z `-0.05`. `update_card_shadows_on_drag` snaps shadows in `DragState.cards` to a lifted state (40 % alpha, `(4, -6)` offset, `(8, 8)` padding). `resize_cards_in_place` extended to keep shadows cheap on window resize. `update_card_entity`'s `despawn_related` is followed by a fresh `add_card_shadow_child` so flips / theme swaps re-attach shadows. Pure `card_shadow_params(is_dragged)` helper unit-tested. 4 new tests. |
+| Stock badge | `655dfde` | A small `·N` chip at the top-right corner of the stock pile shows the remaining count. `update_stock_count_badge` spawns a top-level world entity whose `Transform.translation` is recomputed each tick from `LayoutResource`, so window resize / theme swap don't strand it. Hides via `Visibility::Hidden` when the stock empties — the existing `↺` `StockEmptyLabel` takes over and they never co-render. `Z_STOCK_BADGE = 30` sits between cards and `Z_DROP_OVERLAY`. 4 new tests. |
+
+## Open punch list — release prep (still deferred unless player chooses now)
+
+1. **Cut `v0.11.0`** — meaningful slice since `v0.10.0`: full card-theme system (CARD_PLAN phases 1–7 + theme picker + hayeah art), HUD overhaul (band + fade), session 6's four bug fixes, and session 7's font fallback + four UX feel wins. (`git tag -d v0.1.0` first to clean up the stale local tag.)
+2. **README + CHANGELOG refresh** — README was last touched at `a6b8348` before the Settings picker shipped; doesn't mention card themes, the auto-fade, or any of session 7's UX work.
+3. **Desktop packaging** per `ARCHITECTURE.md §17`. The Arch PKGBUILD exists in `/home/manage/solitaire-quest-pkgbuild/` (separate repo, no remote yet). Pending: app icon, macOS `.icns` + notarisation cert, Windows `.ico` + Authenticode cert, AppImage recipe.
+
+## Open punch list — UX iteration (next-round candidates)
+
+The session-6 list is exhausted. Candidates for a next round, none formally requested by the player:
+
+- **Animated focus ring** (currently a static overlay; could pulse on focus change).
+- **Achievement onboarding pass** — show first-time players the achievement panel after their first win.
+- **Mode-switch keyboard shortcut** from inside the Mode Launcher (today only mouse opens it).
+- **Runtime aspect-ratio fidelity** — hayeah SVGs are ~1.45 h/w; engine layout assumes 1.4. Cards render ~3 % squashed vertically. Cosmetic.
+- **Foundation completion celebration** — when a foundation reaches its King, do a small flourish (sparkle, lift, sound). The auto-complete cascade already covers the win moment, but per-foundation closure is currently silent.
+- **Drag-cancel return animation** — illegal drops snap cards back instantly. A short ease-back tween ("springs back to where it came from") would feel more forgiving.
+
+## Card-theme system (CARD_PLAN.md, fully shipped)
+
+Seven phases landed across `b8fb3fb` → `924a1e2`. End-to-end:
+
+- **Bundled default theme** ships in the binary via `embedded://` — 52 hayeah/playing-cards-assets SVGs (MIT) + a midnight-purple `back.svg` (original work).
+- **User themes** live under `themes://` rooted at `solitaire_engine::assets::user_theme_dir()`. Drop a directory containing `theme.ron` + 53 SVG files; appears in the registry on next launch.
+- **Importer** at `solitaire_engine::theme::import_theme(zip)` validates an archive (20 MB cap, zip-slip rejection, manifest validation, every SVG round-tripped through the rasteriser) and atomically unpacks.
+- **Picker UI** in Settings → Cosmetic — one chip per registered theme; selection persists to `settings.json` as `selected_theme_id` and propagates to live sprites via `react_to_settings_theme_change` → `sync_card_image_set_with_active_theme` → `StateChangedEvent`.
+
+## Resume prompt
+
+```
+You are a senior Rust + Bevy developer working on Solitaire Quest.
+Working directory: <Rusty_Solitaire clone path on this machine — local
+directory may still be named Rusty_Solitare from earlier; that's fine>.
+Branch: master. Direction is OPEN — the session-6 UX punch list is
+fully shipped. The player will choose between cutting v0.11.0, doing
+release prep (README/CHANGELOG/packaging), or starting a new UX
+iteration round.
+
+State: HEAD=655dfde. Local master is 3 commits ahead of origin
+(f6c9166, f712b89, 655dfde unpushed; fdb6c2e and 95df542 already
+pushed). Working tree clean apart from untracked CARD_PLAN.md
+(intentional).
+Build: cargo clippy --workspace --all-targets -- -D warnings clean.
+Tests: 982 passed / 0 failed.
+
+READ FIRST (in order, before doing anything):
+  1. SESSION_HANDOFF.md  — full state, session 7 changelog, punch list
+  2. CLAUDE.md           — hard rules (UI-first, no panics, etc.)
+  3. ARCHITECTURE.md     — crate responsibilities + data flow
+  4. ~/.claude/projects/<this-project>/memory/MEMORY.md
+                         — saved feedback / project context (machine-local;
+                           may be missing on a fresh machine)
+
+DECISION TO ASK THE PLAYER FIRST:
+  A. Push the 3 unpushed commits and cut v0.11.0?
+  B. Skip the tag for now, refresh README + CHANGELOG, then tag?
+  C. Skip release prep entirely and start a new UX iteration round?
+     If C, see the session-7 next-round candidates list (animated
+     focus ring, achievement onboarding, mode-switch keyboard
+     shortcut, aspect-ratio fidelity, foundation completion flourish,
+     drag-cancel return tween).
+
+WORKFLOW NOTES:
+  - Commits use:
+      git -c user.name=funman300 -c user.email=root@vscode.infinity \
+          commit -m "..."
+  - Sub-agents stage + verify only; orchestrator commits.
+  - Every commit must pass build / clippy / test before pushing.
+  - Push to GitHub (origin) — that is the canonical remote.
+
+OPEN AT THE START: ask which of A / B / C. Don't pick unilaterally —
+this is a directional choice, not a tactical one.
+```
--- a/Show More
+++ b/Show More