diff --git a/SESSION_HANDOFF.md b/SESSION_HANDOFF.md index d1d4d83..20184f3 100644 --- a/SESSION_HANDOFF.md +++ b/SESSION_HANDOFF.md @@ -1,24 +1,20 @@ # Solitaire Quest — Session Handoff -**Last updated:** 2026-05-02 (session 9, post-v0.14.0 release prep) — v0.14.0 cut. The Quat bug fixes, the rest of the v0.13.0 candidate list, and the entire replay → upload → web-viewer pipeline are all bundled in this release. Direction now opens for the next round. +**Last updated:** 2026-05-02 (post-v0.15.0) — In-engine replay playback, the Klondike solver + Winnable-deals toggle, a 19th achievement (Cinephile), rolling replay history, and the Bevy default-features trim all shipped under v0.15.0. Direction now opens. ## Status at pause -- **HEAD on origin:** v0.14.0's tag commit (CHANGELOG + handoff refresh). +- **HEAD on origin:** v0.15.0's tag commit. - **Working tree:** clean apart from untracked `CARD_PLAN.md` (intentional). - **Build:** `cargo clippy --workspace --all-targets -- -D warnings` clean. -- **Tests:** **1134 passed / 0 failed** across the workspace. -- **Tags on origin:** `v0.9.0`, `v0.10.0`, `v0.11.0`, `v0.12.0`, `v0.13.0`, `v0.14.0`. +- **Tests:** **1178 passed / 0 failed** across the workspace. +- **Tags on origin:** `v0.9.0`, `v0.10.0`, `v0.11.0`, `v0.12.0`, `v0.13.0`, `v0.14.0`, `v0.15.0`. ## Where we are -v0.14.0 is the largest release since the card-theme system. Three threads land together: +v0.15.0 closes out the post-v0.14.0 candidate list: every item the prior handoff seeded shipped. The major new player-facing pieces are the working "Watch replay" button (in-engine playback with a Stop button overlay), a hand-rolled Klondike solver with the optional "Winnable deals only" toggle, and a rolling history of the last 8 wins. The under-the-hood win is the Bevy default-features trim that drops 51 transitive crates. -1. **The remaining v0.13.0-era UX candidates** — theme thumbnails, daily-challenge calendar, Time Attack auto-save, per-mode bests, time-bonus multiplier slider. -2. **Quat smoke-test bug fixes** — multi-card move validation, softlock detection, deal-tween information leak. -3. **The replay pipeline** — record on win, persist to disk, upload to server, view in browser via a new `solitaire_wasm` crate. The biggest single feature since the card-theme system. - -The card-flight web animations and replay E2E test coverage close out the pipeline. +The post-v0.15.0 candidate list is short — solver-driven hints (now possible since the solver exists), desktop packaging (still pending artwork + signing certs), and a fresh round of UX iteration. Direction is open. ### Design direction (unchanged) @@ -30,55 +26,33 @@ The card-flight web animations and replay E2E test coverage close out the pipeli `github.com/funman300/Rusty_Solitaire` is the canonical repo. Always push there. -## Session 8 + 9 (shipped 2026-05-02) — v0.14.0 - -### v0.13.0-era UX candidates (had landed but missed v0.13.0's tag) +## v0.15.0 (shipped 2026-05-02) | Area | Commit | What landed | |---|---|---| -| Theme thumbnails | `ba527de` | Each Settings → Cosmetic theme chip renders an Ace + back preview pair via `rasterize_svg`. Cached per theme. Missing-SVG themes show a transparent placeholder rather than crashing. | -| Daily-challenge calendar | `1a10476` | 14-dot horizontal calendar in the Profile modal. Today is ringed, completed days fill `STATE_SUCCESS`, missed days fill `BG_ELEVATED`. Caption: "Current streak: N · Longest: M". `PlayerProgress` gains `daily_challenge_history` (capped at 365) and `daily_challenge_longest_streak`. | -| Time Attack auto-save | `0001432` | New sibling `time_attack_session.json` next to `game_state.json`. Atomic .tmp + rename. 30 s auto-save while active + on `AppExit`. Sessions whose 10-min window expired in real time while the app was closed are discarded on load. | -| Per-mode bests | `3984231` | StatsSnapshot gains six `#[serde(default)]` fields (Classic / Zen / Challenge × best_score + fastest_win_seconds). Stats screen renders a "Per-mode bests" section. Lifetime totals continue to roll all modes together. | -| Time-bonus slider | `89c51ab` | Settings → Gameplay slider 0.0–2.0, default 1.0, "Off" at zero. Multiplies the time-bonus shown in the win modal. Cosmetic only — does NOT affect achievement unlock thresholds. | - -### Quat smoke-test bug fixes - -| Area | Commit | What landed | -|---|---|---| -| Move validation (#1) | `f1aeb24` | `solitaire_core::rules::is_valid_tableau_sequence(&[Card]) -> bool` checks every adjacent pair in a moved stack descends one rank with alternating colour. Wired into `move_cards`. Closes the bug where any multi-card lift could be dropped as long as the bottom landed legally. | -| Deal-tween leak (#4) | `3eabc14` | New-game snaps every card sprite to the stock pile position before writing `StateChangedEvent`, so all 52 cards animate from a single deck point during the deal. Previously sprites started from previous-game positions, briefly revealing the prior deal. | -| Softlock detection (#2) | `2716472` | `has_legal_moves` rewritten: walks every potential move source (every stock card, every waste card, the face-up top of every tableau column) against every foundation and every tableau. Previous heuristic returned `true` whenever stock had cards, hiding genuine softlocks. `GameOverScreen` now actually fires for true softlocks. | -| End-game screen (#3) | — | Resolved as downstream of #2. The pre-existing `GameOverScreen` and `WinSummaryOverlay` already cover the close-out paths; the softlock screen just never spawned because the old `has_legal_moves` lied. | - -### Replay pipeline (the major feature) - -| Area | Commit | What landed | -|---|---|---| -| Replay storage | `42535f5` | `solitaire_data::replay::Replay` (seed + draw_mode + mode + score + time + recorded date + ordered move list) and atomic save/load helpers under `/latest_replay.json`. Schema v1; `load` returns None for any other version. | -| Engine recording | `57d1c58` | `RecordingReplay` resource + `ReplayPath` settings. Every successful `MoveRequestEvent` / `DrawRequestEvent` appends to recording; `GameWonEvent` freezes the recording into a `Replay` and persists. Undo intentionally not recorded. New game clears the recording. | -| Stats button | `d9f36bf` | Stats overlay surfaces a "Latest win:" caption + "Watch replay" button. Loads from disk via `LatestReplayResource`. (Full in-engine playback deferred — button currently fires an `InfoToastEvent` describing the replay.) | -| Server upload + fetch | `93182fa` | `POST /api/replays` accepts a `Replay` JSON; `GET /api/replays/:id` returns it. JWT-gated. SQL migration for the new `replays` table. | -| Engine sync | `23c9704` | Engine uploads winning replays automatically when the player has cloud sync configured. Re-uses the existing JWT/refresh-token flow. | -| WASM crate | `5bed43e` | New workspace member `solitaire_wasm` compiles replay-relevant `solitaire_core` types to WebAssembly so a browser can re-execute a replay client-side. `wasm-bindgen` glue. | -| Web viewer | `07b8ecd` | `GET /replays/:id` returns HTML + CSS + the wasm bundle. Browser fetches the replay JSON, rasterises a deal from the seed, and animates the recorded moves. | -| E2E coverage | `3081505` | Server tests covering the full upload → fetch round-trip via `axum::test`. | -| Web flight anim | `1fcd032` | Card-flight tweens on the web side so the browser viewer reads as a real game replay rather than a static dump. | +| Bevy trim | `95fcdad` | `default-features = false` plus a curated explicit feature list. Drops 51 transitive crates including the `bevy_audio` → rodio → cpal 0.15 + symphonia chain (kira handles audio directly). `solitaire_wasm` is bevy-free and unaffected. | +| Replay playback core | `8e90574` | `ReplayPlaybackPlugin` + `ReplayPlaybackState` enum. Iterative DFS through `replay.moves` at `REPLAY_MOVE_INTERVAL_SECS` (0.45 s) firing canonical events. Recording suppression via length-truncation in a sibling system — `game_plugin` untouched. Reset-to-recorded-deal uses direct `GameStateResource` insert to apply the recording's exact `draw_mode`. | +| Replay overlay UI | `9c36b49` | Top-anchored banner (`ReplayOverlayPlugin`): "Replay" label + "Move N of M" progress + Tertiary Stop button. Z = 55 (above HUD, below modals so Settings / Pause / Help still open during playback). | +| Stats button wiring | `02ababa` | Watch Replay button now calls `start_replay_playback` instead of firing a stub toast. `Option>` so headless tests without `ReplayPlaybackPlugin` still pass. | +| Replay history | `13a8a01` | Rolling list of 8 wins at `/replays.json`. Legacy `latest_replay.json` migrates forward on first launch via `migrate_legacy_latest_replay`. Stats overlay's selector — Prev / Next chips + "Replay N / M" caption — lets the player step through older wins. | +| Cinephile achievement | `bf660df` | 19th achievement; unlocks on `Playing → Completed` transition (not on Stop, which goes Playing → Inactive). README count + ARCHITECTURE.md §11 entry updated. | +| Solver + toggle | `8a5fa87` | `solitaire_core::solver::try_solve(seed, draw_mode, &SolverConfig) -> SolverResult { Winnable, Unwinnable, Inconclusive }`. Iterative DFS, 64-bit canonical state hash, priority-ordered move enumeration, two budget knobs (100k moves / 200k states default). Median solve 2 ms, pathological 120 ms. Settings → Gameplay toggle "Winnable deals only" (default off) makes `handle_new_game` retry seeds up to `SOLVER_DEAL_RETRY_CAP = 50` attempts. Daily / replays / explicit-seed bypass the solver. | ## Open punch list ### Release prep -1. **Smoke-test on the alex machine** after pulling — confirm Quat's three bug fixes hold up in real gameplay, and try the new replay button + web viewer end-to-end. -2. **Desktop packaging** per `ARCHITECTURE.md §17`. The Arch PKGBUILD exists in `/home/manage/solitaire-quest-pkgbuild/` (separate repo). Pending: app icon, macOS `.icns` + notarisation cert, Windows `.ico` + Authenticode cert, AppImage recipe. -### UX iteration (next-round candidates) +1. **Smoke-test on a real game**: confirm the new replay playback feels right at 0.45 s/move; verify the Winnable-deals toggle doesn't introduce a visible stall on a typical machine; try the rolling-history selector. +2. **Desktop packaging** per `ARCHITECTURE.md §17`. Arch PKGBUILD exists in `/home/manage/solitaire-quest-pkgbuild/` (separate repo). Pending: app icon, macOS `.icns` + notarisation cert, Windows `.ico` + Authenticode cert, AppImage recipe. -- **Solver-at-deal toggle** (Quat investigation #1, still deferred): add a Settings → Gameplay toggle "Winnable deals only" rather than baking solver-only into every deal. Lightest middle ground. -- **Disable Bevy's default audio feature** (Quat investigation #2, still deferred): one-line `default-features = false` swap on the workspace `bevy =` line, re-enable explicitly the features the engine uses (`render`, `bevy_winit`, `2d`, `bevy_window`, `png`, `bevy_text`, `bevy_ui`, `bevy_log`, `bevy_asset`, `default_font`, `bevy_state`). Drops ~50 transitive crates including the rodio + symphonia stack the project doesn't use (kira handles audio). -- **In-engine replay playback** — promote the "Watch replay" button from a stub toast to a real playback overlay that re-runs the recorded moves with `CardAnimation` tweens. The wasm crate already proves the playback math; the in-engine version reuses the same execute logic against the live game state. -- **Per-replay history** — currently single-slot at `latest_replay.json`. A "best replay per mode" bucket or a recent-N rolling list would let players revisit notable wins. -- **Solver-driven hint system** — extend the existing hint toggle so a deal-time solver provides higher-quality hints (currently a heuristic). Requires the solver from the toggle work above. -- **Achievement: "won via replay path"** — track when a player wins a deal whose previously-saved replay also won the same deal. Mostly fun; trivial scope. +### Next-round candidates + +- **Solver-driven hints** — the existing hint system uses a heuristic; promote it to ask `try_solve` for the actual best move. Scope: small wrapper around the solver's `enumerate_moves` plus the existing hint plumbing. Now unblocked. +- **Replay-playback rate slider** — the 0.45 s/move pace is hardcoded; a Settings slider in the same row as tooltip-delay / time-bonus would let power users speed up older replays. +- **Solver progress overlay** — when "Winnable deals only" is on, a brief "checking deal…" toast surfaces after ~500 ms so the player isn't confused by the rare worst-case stall. +- **Solver-on-AsyncComputeTaskPool** — current solver runs synchronously on the main thread. Worst-case 50 attempts × 120 ms = 6 s of UI stall on pathological seeds. Async + cancel button would be safer. +- **Per-deal "won previously" indicator** — the rolling replay history's seeds make this easy: when a new game starts on a seed the player has already won, surface a tiny indicator on the HUD. +- **Replay sharing** — `replays.json` is per-machine. Allow a player to copy a replay's URL (already wired via `solitaire_server`) and post it elsewhere. The web-viewer already exists. ## Card-theme system (CARD_PLAN.md, fully shipped) @@ -95,17 +69,18 @@ Seven phases landed across `b8fb3fb` → `924a1e2` in v0.11.0; v0.13.0's `7ed4f2 You are a senior Rust + Bevy developer working on Solitaire Quest. Working directory: . -Branch: master. Direction is OPEN — v0.14.0 just shipped covering the -Quat bug fixes, the v0.13.0 candidate tail, and the entire -replay-pipeline feature. +Branch: master. Direction is OPEN — v0.15.0 just shipped covering +in-engine replay playback, the Klondike solver + Winnable-deals +toggle, replay history, the Cinephile achievement, and the Bevy +default-features trim. -State: HEAD at v0.14.0. Working tree clean apart from untracked +State: HEAD at v0.15.0. Working tree clean apart from untracked CARD_PLAN.md (intentional). Build: cargo clippy --workspace --all-targets -- -D warnings clean. -Tests: 1134 passed / 0 failed. +Tests: 1178 passed / 0 failed. READ FIRST (in order, before doing anything): - 1. SESSION_HANDOFF.md — v0.14.0 changelog + open punch list + 1. SESSION_HANDOFF.md — v0.15.0 changelog + open punch list 2. CHANGELOG.md — release-by-release record 3. CLAUDE.md — hard rules (UI-first, no panics, etc.) 4. ARCHITECTURE.md — crate responsibilities + data flow @@ -114,16 +89,16 @@ READ FIRST (in order, before doing anything): may be missing on a fresh machine) DECISION TO ASK THE PLAYER FIRST: - A. Smoke-test v0.14.0 on the alex machine first to confirm the - three Quat bug fixes hold up in real gameplay and the replay - pipeline works end-to-end (record → upload → web viewer). - B. Take the deferred Bevy-audio-feature trim (Quat investigation - #2) — one-line workspace edit, ~50 fewer transitive crates. - C. Take the deferred solver toggle (Quat investigation #1): add - "Winnable deals only" Settings toggle. Larger. - D. Promote the in-engine "Watch replay" button to real playback. - E. Pick from the remaining "next-round candidates" in this doc. - F. Take the deferred desktop-packaging item (needs artwork + + A. Smoke-test v0.15.0 in a real game session. Solver, replay + playback, replay history selector, Cinephile achievement. + B. Take solver-driven hints (now possible with the solver in place). + Replace the heuristic hint with `try_solve`'s best-move + suggestion. + C. Move the solver to AsyncComputeTaskPool with a "checking deal…" + progress toast and a cancel button. Eliminates the worst-case + 6 s UI stall. + D. Pick from the remaining "next-round candidates" in this doc. + E. Take the deferred desktop-packaging item (needs artwork + signing certs from the user). WORKFLOW NOTES: @@ -136,5 +111,5 @@ WORKFLOW NOTES: - 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–F. Don't pick unilaterally. +OPEN AT THE START: ask which of A–E. Don't pick unilaterally. ```