From 9ff48ace5ba69f02d3b59346614a98dc958784f3 Mon Sep 17 00:00:00 2001 From: funman300 Date: Wed, 6 May 2026 18:17:07 -0700 Subject: [PATCH] docs: refresh handoff + populate CHANGELOG [Unreleased] for v0.19.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three commits sit on top of v0.18.0 — async H-key hint (3e11e9e), persistent replay share URLs (42d90b1), and the auto-save flake fix (91b7605). [Unreleased] now describes them as Changed / Fixed bullets ready to promote to a [0.19.0] section whenever the next cut feels right. SESSION_HANDOFF.md marks v0.18.0 punch-list items B and D as shipped, preserves C (desktop packaging) as still gated on artwork + signing certs, and refreshes the resume prompt's A–D menu around the v0.19.0-cut decision. The previous handoff's `-c user.name=...` workflow note is replaced with a pointer to the system git config (which is now correct on this machine via the v0.18.0 push session's `gh auth setup-git`). Co-Authored-By: Claude Opus 4.7 --- CHANGELOG.md | 54 +++++++++++- SESSION_HANDOFF.md | 207 ++++++++++++++++++++++----------------------- 2 files changed, 152 insertions(+), 109 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7dcf8d1..610fce1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,59 @@ project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] -_Nothing yet._ +Closes the v0.18.0 punch list's items B and D and clears the +`auto_save_writes_after_30_seconds` test flake. + +### Changed + +- **H-key hint runs on `AsyncComputeTaskPool`** (`3e11e9e`). The + synchronous `try_solve_from_state` call on every H press is gone; + `handle_keyboard_hint` now spawns a task whose result the new + `pending_hint::poll_pending_hint_task` system surfaces one frame + later. New `PendingHintTask` resource carries the in-flight handle + plus `move_count_at_spawn` for staleness detection; + `drop_pending_hint_on_state_change` cancels the task whenever the + game state shifts; `PendingHintTask::spawn` implements + cancel-on-replace so two quick H presses keep at most one task in + flight. Mirrors the v0.18.0 `PendingNewGameSeed` template. + `emit_hint_visuals` and `find_heuristic_hint` are extracted as + `pub` helpers so the polling system can call them. +- **Persistent replay share URLs** (`42d90b1`). v0.18.0's + `LastSharedReplayUrl` was an in-memory resource wiped on quit — + the player had to share within the session of the win. + `solitaire_data::Replay` now carries a `share_url: Option` + field with `#[serde(default)]` (no `REPLAY_SCHEMA_VERSION` bump + needed; older `replays.json` files load unchanged with `share_url + == None` on every entry). `poll_replay_upload_result` writes the + resolved URL into `replays[0].share_url` and persists the updated + history via `save_replay_history_to`. The Stats overlay's + "Copy share link" button reads from + `history.0.replays[selected.0].share_url`, so the Prev/Next + selector's currently-displayed replay drives the clipboard + contents — each historical win keeps its own URL. + `LastSharedReplayUrl` removed (its role is now subsumed by the + share_url field on the replay record). + +### Fixed + +- **`auto_save_writes_after_30_seconds` test flake.** The test's + single-frame `app.update()` was sensitive to first-frame + `Time::delta_secs()` variance under heavy parallel cargo-test + load, and to production-disk `~/.local/share/solitaire_quest/game_state.json` + state leaking into the test world via `GamePlugin::build`'s load + path. `test_app` now resets `PendingRestoredGame(None)` after + plugin build (preventing the dev machine's saved-game state from + tripping the auto-save guard) and the test re-arms the timer in a + small bounded loop until the file appears (robust against + first-frame Time variance). No production-code change. + +### Stats + +- 1170 passing tests (was 1166 at v0.18.0 close — 1 in + `solitaire_data` for share_url backwards-compat, 4 in + `solitaire_engine` for async hint coverage and the persistent + share URL persistence path). +- Zero clippy warnings under `--workspace --all-targets -- -D warnings`. ## [0.18.0] — 2026-05-06 diff --git a/SESSION_HANDOFF.md b/SESSION_HANDOFF.md index c74328b..bae6b1d 100644 --- a/SESSION_HANDOFF.md +++ b/SESSION_HANDOFF.md @@ -1,58 +1,53 @@ # Solitaire Quest — Session Handoff -**Last updated:** 2026-05-06 (post-v0.18.0 draft) — 24 commits since -the v0.17.0 tag bundle the launch-experience round (Restore prompt + -auto-show Home / mode picker), the MSSC-style Home picker rework -(header chips, draw-mode chips, picture-tile mode cards, Today's -Event callout, glyph fixes), the last solver hot path moving onto -`AsyncComputeTaskPool`, "Won before" HUD chip, "Copy share link" -Stats button, the `N` keybinding finally routing through the real -Confirm/Cancel modal, Esc-on-modal layering fixes, and the -unified-3.0 Claude rule set (CLAUDE.md / CLAUDE_SPEC.md / -CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md). Test-discipline prune -removed 43 low-value tests in the same window. +**Last updated:** 2026-05-06 (post-v0.18.0, [Unreleased] accumulating +v0.19.0 candidates) — v0.18.0 tagged + pushed at `bfcd05f`. Three +commits sit on top: the H-key hint moved onto +`AsyncComputeTaskPool` (closing the last synchronous solver hot +path), persistent replay share URLs (no more +in-session-only sharing), and a fix for the +`auto_save_writes_after_30_seconds` test flake. ## Status at pause -- **HEAD on origin:** `v0.17.0-24-gc497c31` (24 ahead of v0.17.0, - not yet tagged). -- **Working tree:** clean. +- **HEAD on origin:** `42d90b1` (the persistent share-link + commit). Local HEAD is one ahead at `91b7605` (auto-save flake + fix), with this round's `[Unreleased]` doc refresh staged on + top. +- **Working tree:** modified — `CHANGELOG.md` and + `SESSION_HANDOFF.md` carry the `[Unreleased]` doc updates. - **Build:** `cargo clippy --workspace --all-targets -- -D warnings` clean (verified this session). -- **Tests:** **1166 passing / 0 failing** across the workspace - (verified this session). The first run flaked once on - `solitaire_engine::game_plugin::tests::auto_save_writes_after_30_seconds` - — a one-frame `app.update()` test that depends on `time.delta_secs()` - on an otherwise-fresh `App`. Reproduced clean on the second run; - passes in isolation. Worth tightening if it flakes again, but - not blocking the v0.18.0 cut. -- **Tags on origin:** `v0.9.0` through `v0.17.0`. -- **CHANGELOG:** v0.18.0 entry drafted in `[Unreleased]`'s slot — - ready for tag once build + tests are reverified. +- **Tests:** **1170 passing / 0 failing** across the workspace + (verified this session). + `auto_save_writes_after_30_seconds` reverified stable across + three back-to-back runs after the flake fix. +- **Tags on origin:** `v0.9.0` through `v0.18.0`. +- **CHANGELOG:** `[Unreleased]` populated with the three + post-v0.18.0 commits — promote to `[0.19.0]` whenever the + next cut feels right. ## Where we are -v0.17.0's punch list had four candidates (A–D); two of the three -non-packaging items shipped in this round: +v0.18.0's resume-prompt menu (A–D) is mostly closed: -- **B — "Won previously" HUD indicator:** shipped in `bdac754`. -- **C — Replay sharing:** shipped in `540869c` ("Copy share link" - Stats button + clipboard via `arboard`, in-memory `LastSharedReplayUrl`). +- ~~**A — Tag v0.18.0:**~~ shipped at `bfcd05f`. +- ~~**B — Solver-on-`AsyncComputeTaskPool` for the H-key hint:**~~ + shipped at `3e11e9e`. New module `pending_hint.rs` carries the + `PendingHintTask` resource and `poll_pending_hint_task` system, + mirroring the `PendingNewGameSeed` pattern. +- **C — Desktop packaging:** unchanged, still gated on artwork + + signing certs from the player. +- ~~**D — Persistent share link:**~~ shipped at `42d90b1`. + `Replay.share_url: Option` (with `#[serde(default)]`), + Stats overlay's "Copy share link" reads from + `history.0.replays[selected.0].share_url`, + `LastSharedReplayUrl` resource removed. -Item **A** (solver-on-`AsyncComputeTaskPool`) shipped *partially* in -`d489e7a` — the winnable-only seed-selection path is now async with -cancel-on-replace. The hint path (`H` key, -`try_solve_with_first_move` / `try_solve_from_state`) is still -synchronous. The proven `PendingNewGameSeed` template is the -template for the hint port. - -Item **D** (desktop packaging) is unchanged — still gated on -artwork + signing certs from the player. - -The launch experience is also substantially different from v0.17.0: -on first launch with a saved game the player now sees the Restore -prompt; on every launch (after splash + restore resolution) they see -the auto-show Home / mode picker. +The `auto_save_writes_after_30_seconds` flake has been fixed at +`91b7605` by clearing `PendingRestoredGame` in the test fixture +and re-arming the timer in a small bounded loop until the file +appears. No production-code change. ### Design direction (unchanged) @@ -68,83 +63,80 @@ the auto-show Home / mode picker. `github.com/funman300/Rusty_Solitaire` is the canonical repo. Always push there. -## v0.18.0 (drafted 2026-05-06, not yet tagged) +## v0.19.0 candidates ([Unreleased] in CHANGELOG) | Area | Commit | What landed | |---|---|---| -| Restore prompt | `3c7a0eb` + `f863d85` | Welcome-back modal on launch when an in-progress save exists; save preserved across exits while the prompt is unanswered. | -| Async winnable-only seeds | `d489e7a` | `PendingNewGameSeed` resource + `poll_pending_new_game_seed` running `.before(GameMutation)`. Fixes the worst-case 6 s UI stall on a New Game click. Cancel-on-replace contract covered by tests. | -| Won-before HUD chip | `bdac754` | Reads `ReplayHistoryResource`; lights `✓ Won before` on tier-2 row when current `(seed, draw_mode, mode)` is in history. | -| Copy share link | `540869c` | `arboard` clipboard + new Stats button + `SyncProvider::push_replay` returning the share URL. In-memory only; per-session sharing. | -| MSSC Home picker | `ae40a1d`, `b73d246`, `9fe650f`, `40d6e0a`, `c30b04e`, `d065d49` | Header stats strip (clickable → Profile), draw-mode chips, per-mode score/streak chips, Today's Event callout on Daily, picture-tile 2-up grid with FiraMono-covered glyphs (♣ ◆ ○ ▲ →). | -| Auto-show Home | `dd63261`, `b7c3a49`, `c497c31` | Auto-shows after splash; gated on Restore prompt; freezes timers (elapsed + Time Attack) while up. | -| `N` opens real modal | `93660c2` | Removes the "Press N again" double-tap; routes through `ConfirmNewGameScreen`. `Shift+N` retains the bypass. | -| Win Summary keyboard | `17e0737` | Enter dismisses + starts a fresh deal. | -| Esc-on-modal fixes | `08b006f`, `d48b948`, `9aa0dd2` | Esc no longer opens Pause underneath the modal it just closed; Home maps Esc to Cancel; Restore maps Esc to Continue; topmost-modal-wins when Profile stacks on Home. | -| Layout fixes | `a4bc063`, `cc63532` | Settings rows full-width with label-spacer-cluster; popover rows excluded from action-bar auto-fade. | -| Empty-state copy | `56e2e6f` | Leaderboard / Achievements onboarding hints; volume hotkeys emit toast feedback. | -| Test prune | `a49a340` | −43 low-value tests; future briefs request behaviour contracts only. | -| Docs unified-3.0 | `f2f30c8` | Adopts CLAUDE.md / CLAUDE_SPEC.md / CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md; trims duplicated rule passages. | +| Async H-key hint | `3e11e9e` | New `pending_hint.rs` module: `PendingHintTask` resource, `poll_pending_hint_task` + `drop_pending_hint_on_state_change` systems, cancel-on-replace, stale-state guard via `move_count_at_spawn`. Removes the last synchronous solver hot path. | +| Persistent share URLs | `42d90b1` | `Replay.share_url: Option` with `#[serde(default)]`. `poll_replay_upload_result` writes into `replays[0].share_url` + persists. Stats Copy button reads from the selected replay. `LastSharedReplayUrl` deleted. | +| Auto-save flake fix | `91b7605` | `test_app` clears `PendingRestoredGame(None)` after plugin build (preventing dev-machine `game_state.json` from leaking into tests); `auto_save_writes_after_30_seconds` re-arms the timer in a bounded loop instead of single-frame. No production-code change. | ## Open punch list -### Carried forward from v0.17.0 +### Carried forward -- **Solver-on-`AsyncComputeTaskPool` for the H-key hint** — - remaining synchronous solver hot path. The seed-selection port - in `d489e7a` is the template: `PendingHintTask` resource, polling - system running `.before(GameMutation)`, cancel-on-replace, fall - back to the heuristic on inconclusive. Diff should stay scoped - to `input_plugin.rs` plus a small `pending_hint.rs`. - **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. +- **Per-mode artwork** for the Home picker tiles. Currently + Unicode glyphs from FiraMono's actual coverage as placeholders + (♣ ◆ ○ ▲ →). When real artwork lands, swap each tile's `Text` + node for an `Image` node — tile layout, focus order, click + handling, and chip rendering are unchanged. -### New this round +### Possible next-round candidates -- **Persistent share link.** `LastSharedReplayUrl` is in-memory only - — the player must share within the session of the win. If - cross-session sharing turns into a real ask, persist alongside - the rolling replay history. -- **Per-mode artwork.** Picture tiles use Unicode glyphs as - placeholders chosen from FiraMono's actual coverage. When real - artwork lands, swap each tile's `Text` node for an `Image` node - — tile layout, focus order, click handling, and chip rendering - are unchanged. +- **Cut v0.19.0** — `[Unreleased]` is a coherent three-commit + bundle (one feature, one persistence enhancement, one test + hygiene fix). Tag whenever it feels right. +- **Pending hint task on `.before(GameMutation)`** — currently + `poll_pending_hint_task` runs on `Update` without explicit + ordering. Won't bite in practice (the result is purely + visual — no game state mutation), but matches the seed-async + template precisely. +- **Settings UI for share-link visibility** — once persistent, + surfacing whether a given replay has a URL on the Prev/Next + selector caption (e.g. "Replay 3 / 8 \u{2022} Shareable") is a + natural micro-feature. Two-line change in + `format_replay_caption`. -### Process notes (from this round) +### Process notes -- **Test inflation pattern (resolved this round):** older agent - briefs reflexively asked for ≥3 tests per feature, producing 43 - low-value coverage entries on stdlib/serde-derive mechanics. Going - forward, ask for tests that pin behaviour contracts or - regressions on real bugs only. See - `feedback_test_discipline.md` in auto-memory. -- **Solver async refactor sequencing (worked this round):** rather - than porting the whole solver-on-main-thread surface in one PR - (the rollback case from before v0.17.0), the - `PendingNewGameSeed` work shipped one well-bounded path with two - tests covering the happy path and cancel-on-replace. The hint - port should follow the same shape. +- **Test discipline (continuing).** v0.19.0 candidates added 4 + tests across `solitaire_data` + `solitaire_engine`. Each pins + a real behaviour contract (backwards-compat deserialisation, + spawn → poll → emit, cancel-on-replace, persist after upload) + rather than a stdlib / derive round-trip. The async hint port + removed 2 stale synchronous tests when their behaviours moved + to the new module. +- **Async port template (worked this round):** the H-key port + followed `d489e7a`'s `PendingNewGameSeed` shape one-to-one — + resource holds `Option>` plus snapshot data; spawn + helper drops any in-flight task before assigning new; poll + system runs in `Update`; cancel-on-state-change runs `.chain()`-ed + before poll. Two tests cover happy path + cancel. +- **Persistence migration template:** for purely-additive replay + fields, `#[serde(default)]` is the cheap migration. Bumping + `REPLAY_SCHEMA_VERSION` would have wiped every player's rolling + history (the loader rejects mismatched schema), so additive + changes should default-deserialise rather than version-bump. ## Resume prompt ``` You are a senior Rust + Bevy developer working on Solitaire Quest. Working directory: . -Branch: master. Direction is OPEN — v0.18.0 has been drafted but -not tagged: 24 commits past v0.17.0 cover the launch-experience -round, MSSC Home picker, async winnable-only seeds, Won-before -HUD, Copy share link, N-key flow rework, Esc-layering fixes, and -the unified-3.0 Claude rule set. +Branch: master. v0.18.0 is tagged. Three commits sit on top: +async H-key hint, persistent replay share URLs, and an +auto-save test flake fix. -State: HEAD at v0.17.0-24-gc497c31. Working tree clean. -CHANGELOG.md has the v0.18.0 entry slotted under [Unreleased]. +State: HEAD at 91b7605 (auto-save flake fix on top of v0.18.0 ++ async hint + persistent share URL). READ FIRST (in order, before doing anything): 1. SESSION_HANDOFF.md — this file - 2. CHANGELOG.md — v0.18.0 draft entry + 2. CHANGELOG.md — [Unreleased] holds the v0.19.0 draft 3. CLAUDE.md — unified-3.0 rule set 4. CLAUDE_SPEC.md — formal architecture spec 5. ARCHITECTURE.md — crate responsibilities + data flow @@ -154,26 +146,25 @@ READ FIRST (in order, before doing anything): fresh machine) DECISION TO ASK THE PLAYER FIRST: - A. Tag v0.18.0 — promote `[Unreleased]` to `[0.18.0]` (already - done in this session's draft), reverify build + clippy + - tests, tag, push. Mechanical close-out. - B. Solver-on-AsyncComputeTaskPool for the H-key hint, using the - `d489e7a` seed-selection port as template. Last synchronous - solver hot path. Smallest delta on the open punch list. - C. Desktop packaging — needs artwork + signing certs from the + A. Cut v0.19.0 — promote [Unreleased] to [0.19.0], tag, + push. Mechanical close-out. + B. Desktop packaging — needs artwork + signing certs from the player; can't be driven by the agent alone. - D. Persistent share link — store the URL alongside replay - history so cross-session sharing works. + C. Per-mode artwork — replace Home picker tile glyphs with real + images once art lands. + D. Smaller polish ideas in the punch list (pending_hint + ordering hardening, share-link visibility on selector caption). WORKFLOW NOTES: - - Commits use: - git -c user.name=funman300 -c user.email=root@vscode.infinity \ - commit -m "..." + - Use the system git config (already correct: funman300 / + funman300@gmail.com). The previous handoff's `-c user.name=...` + workflow was for a different machine. - When attributing playtester feedback in commits/docs, use "Quat" not "Rhys" (saved feedback memory). - 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. + - Push to GitHub (origin) via `gh auth setup-git` (already wired + on this machine after v0.18.0 was cut). OPEN AT THE START: ask which of A–D. Don't pick unilaterally. ```