Ferrous-Solitaire/SESSION_HANDOFF.md

# Solitaire Quest — Session Handoff

**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:** `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:** **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.18.0's resume-prompt menu (A–D) is mostly closed:

- ~~**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<String>` (with `#[serde(default)]`),
  Stats overlay's "Copy share link" reads from
  `history.0.replays[selected.0].share_url`,
  `LastSharedReplayUrl` resource removed.

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)

- **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`
  (machine-local).

### Canonical remote

`github.com/funman300/Rusty_Solitaire` is the canonical repo.
Always push there.

## v0.19.0 candidates ([Unreleased] in CHANGELOG)

| Area | Commit | What landed |
|---|---|---|
| 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<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. |
| 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

- **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.

### Possible next-round candidates

- **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

- **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<Task<...>>` 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: <Rusty_Solitaire clone path on this machine>.
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 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        — [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
  6. ~/.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. 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.
  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:
  - 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) 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.
```