docs: refresh handoff + populate CHANGELOG [Unreleased] for v0.19.0

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 <noreply@anthropic.com>

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<String>`
+  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
 

SESSION_HANDOFF.md

@@ -1,58 +1,53 @@
 # Solitaire Quest — Session Handoff
 
-**Last updated:** 2026-05-06 (post-v0.18.0 draft) — 24 commits since
+**Last updated:** 2026-05-06 (post-v0.18.0, [Unreleased] accumulating
-the v0.17.0 tag bundle the launch-experience round (Restore prompt +
+v0.19.0 candidates) — v0.18.0 tagged + pushed at `bfcd05f`. Three
-auto-show Home / mode picker), the MSSC-style Home picker rework
+commits sit on top: the H-key hint moved onto
-(header chips, draw-mode chips, picture-tile mode cards, Today's
+`AsyncComputeTaskPool` (closing the last synchronous solver hot
-Event callout, glyph fixes), the last solver hot path moving onto
+path), persistent replay share URLs (no more
-`AsyncComputeTaskPool`, "Won before" HUD chip, "Copy share link"
+in-session-only sharing), and a fix for the
-Stats button, the `N` keybinding finally routing through the real
+`auto_save_writes_after_30_seconds` test flake.
-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.
 
 ## Status at pause
 
-- **HEAD on origin:** `v0.17.0-24-gc497c31` (24 ahead of v0.17.0,
+- **HEAD on origin:** `42d90b1` (the persistent share-link
-  not yet tagged).
+  commit). Local HEAD is one ahead at `91b7605` (auto-save flake
-- **Working tree:** clean.
+  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
+- **Tests:** **1170 passing / 0 failing** across the workspace
-  (verified this session). The first run flaked once on
+  (verified this session).
-  `solitaire_engine::game_plugin::tests::auto_save_writes_after_30_seconds`
+  `auto_save_writes_after_30_seconds` reverified stable across
-  — a one-frame `app.update()` test that depends on `time.delta_secs()`
+  three back-to-back runs after the flake fix.
-  on an otherwise-fresh `App`. Reproduced clean on the second run;
+- **Tags on origin:** `v0.9.0` through `v0.18.0`.
-  passes in isolation. Worth tightening if it flakes again, but
+- **CHANGELOG:** `[Unreleased]` populated with the three
-  not blocking the v0.18.0 cut.
+  post-v0.18.0 commits — promote to `[0.19.0]` whenever the
-- **Tags on origin:** `v0.9.0` through `v0.17.0`.
+  next cut feels right.
-- **CHANGELOG:** v0.18.0 entry drafted in `[Unreleased]`'s slot —
-  ready for tag once build + tests are reverified.
 
 ## Where we are
 
-v0.17.0's punch list had four candidates (A–D); two of the three
+v0.18.0's resume-prompt menu (A–D) is mostly closed:
-non-packaging items shipped in this round:
 
-- **B — "Won previously" HUD indicator:** shipped in `bdac754`.
+- ~~**A — Tag v0.18.0:**~~ shipped at `bfcd05f`.
-- **C — Replay sharing:** shipped in `540869c` ("Copy share link"
+- ~~**B — Solver-on-`AsyncComputeTaskPool` for the H-key hint:**~~
-  Stats button + clipboard via `arboard`, in-memory `LastSharedReplayUrl`).
+  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<String>` (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
+The `auto_save_writes_after_30_seconds` flake has been fixed at
-`d489e7a` — the winnable-only seed-selection path is now async with
+`91b7605` by clearing `PendingRestoredGame` in the test fixture
-cancel-on-replace. The hint path (`H` key,
+and re-arming the timer in a small bounded loop until the file
-`try_solve_with_first_move` / `try_solve_from_state`) is still
+appears. No production-code change.
-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.
 
 ### 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 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. |
-| 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. |
+| Persistent share URLs | `42d90b1` | `Replay.share_url: Option<String>` with `#[serde(default)]`. `poll_replay_upload_result` writes into `replays[0].share_url` + persists. Stats Copy button reads from the selected replay. `LastSharedReplayUrl` deleted. |
-| Won-before HUD chip | `bdac754` | Reads `ReplayHistoryResource`; lights `✓ Won before` on tier-2 row when current `(seed, draw_mode, mode)` is in history. |
+| 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. |
-| 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. |
 
 ## 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
+- **Cut v0.19.0** — `[Unreleased]` is a coherent three-commit
-  — the player must share within the session of the win. If
+  bundle (one feature, one persistence enhancement, one test
-  cross-session sharing turns into a real ask, persist alongside
+  hygiene fix). Tag whenever it feels right.
-  the rolling replay history.
+- **Pending hint task on `.before(GameMutation)`** — currently
-- **Per-mode artwork.** Picture tiles use Unicode glyphs as
+  `poll_pending_hint_task` runs on `Update` without explicit
-  placeholders chosen from FiraMono's actual coverage. When real
+  ordering. Won't bite in practice (the result is purely
-  artwork lands, swap each tile's `Text` node for an `Image` node
+  visual — no game state mutation), but matches the seed-async
-  — tile layout, focus order, click handling, and chip rendering
+  template precisely.
-  are unchanged.
+- **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
+- **Test discipline (continuing).** v0.19.0 candidates added 4
-  briefs reflexively asked for ≥3 tests per feature, producing 43
+  tests across `solitaire_data` + `solitaire_engine`. Each pins
-  low-value coverage entries on stdlib/serde-derive mechanics. Going
+  a real behaviour contract (backwards-compat deserialisation,
-  forward, ask for tests that pin behaviour contracts or
+  spawn → poll → emit, cancel-on-replace, persist after upload)
-  regressions on real bugs only. See
+  rather than a stdlib / derive round-trip. The async hint port
-  `feedback_test_discipline.md` in auto-memory.
+  removed 2 stale synchronous tests when their behaviours moved
-- **Solver async refactor sequencing (worked this round):** rather
+  to the new module.
-  than porting the whole solver-on-main-thread surface in one PR
+- **Async port template (worked this round):** the H-key port
-  (the rollback case from before v0.17.0), the
+  followed `d489e7a`'s `PendingNewGameSeed` shape one-to-one —
-  `PendingNewGameSeed` work shipped one well-bounded path with two
+  resource holds `Option<Task<...>>` plus snapshot data; spawn
-  tests covering the happy path and cancel-on-replace. The hint
+  helper drops any in-flight task before assigning new; poll
-  port should follow the same shape.
+  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: <Rusty_Solitaire clone path on this machine>.
-Branch: master. Direction is OPEN — v0.18.0 has been drafted but
+Branch: master. v0.18.0 is tagged. Three commits sit on top:
-not tagged: 24 commits past v0.17.0 cover the launch-experience
+async H-key hint, persistent replay share URLs, and an
-round, MSSC Home picker, async winnable-only seeds, Won-before
+auto-save test flake fix.
-HUD, Copy share link, N-key flow rework, Esc-layering fixes, and
-the unified-3.0 Claude rule set.
 
-State: HEAD at v0.17.0-24-gc497c31. Working tree clean.
+State: HEAD at 91b7605 (auto-save flake fix on top of v0.18.0
-CHANGELOG.md has the v0.18.0 entry slotted under [Unreleased].
++ 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
+  A. Cut v0.19.0 — promote [Unreleased] to [0.19.0], tag,
-     done in this session's draft), reverify build + clippy +
+     push. Mechanical close-out.
-     tests, tag, push. Mechanical close-out.
+  B. Desktop packaging — needs artwork + signing certs from the
-  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
      player; can't be driven by the agent alone.
-  D. Persistent share link — store the URL alongside replay
+  C. Per-mode artwork — replace Home picker tile glyphs with real
-     history so cross-session sharing works.
+     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:
+  - Use the system git config (already correct: funman300 /
-      git -c user.name=funman300 -c user.email=root@vscode.infinity \
+    funman300@gmail.com). The previous handoff's `-c user.name=...`
-          commit -m "..."
+    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.
 ```