Ferrous-Solitaire/SESSION_HANDOFF.md

# Solitaire Quest — Session Handoff

**Last updated:** 2026-05-07 — `[Unreleased]` accumulating v0.20
candidates. Seven commits sit on top of v0.19.0: three close items
from v0.19.0's punch list (pull-failure flake, smart-window-size
opt-out, Shareable badge), one extends Help cheat-sheet coverage,
and three open a new performance / portability arc — F3 FPS
overlay, Android build target (first working APK), and the matching
developer-setup runbook. The Android build is the load-bearing
change: `solitaire_app` now compiles into both a desktop `bin` and
an Android `cdylib` from the same source.

## Status at pause

- **HEAD on origin:** `59424a3` (post-Android-runbook commit).
- **Working tree:** modified — `CHANGELOG.md` and
  `SESSION_HANDOFF.md` carry the v0.20-candidates promotion + this
  refresh, ready to commit. `artwork/` remains untracked.
- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
  clean (verified this session).
- **Tests:** **1170 passing / 0 failing** across the workspace
  (verified this session). The previously-flaky
  `pull_failure_sets_error_status` is fixed; no known flakes remain.
- **Tags on origin:** `v0.9.0` through `v0.19.0`.

## Where we are

v0.19.0's "Possible next-round candidates" list shipped 3 of 4:

- ~~**`pull_failure_sets_error_status` flake fix:**~~ shipped at
  `67c150b`.
- ~~**Settings UI for smart-default-size opt-out:**~~ shipped at
  `e1b8766`.
- ~~**Persistent share link URL on selector caption:**~~ shipped at
  `9b065e5` (as a "Shareable" badge on the Latest-win caption —
  the Prev/Next selector chips don't have a live spawn site yet,
  so the badge attaches to the existing single-replay caption).
- **App icon round** — still open. 11 PNGs generated by
  `artwork/Icon Export.html` are *not* in the `artwork/` directory
  any more (current `artwork/` holds the reverted Rusty Pixel
  card PNGs); icon-export needs to be re-run before this item can
  be picked up.

Two new threads opened that weren't on any prior punch list:

- **F3 FPS / frame-time overlay** (`690e1d2`). `DiagnosticsHudPlugin`
  wraps `FrameTimeDiagnosticsPlugin`; F3 toggles a top-right
  readout. Hidden by default; primarily a developer affordance.
- **Android build target** (`fb8b2ac` + `59424a3`).
  `solitaire_app` is now a bin + cdylib hybrid. `cargo apk build`
  produces a 54 MB APK with full assets. Five gating points
  resolved (split, manifest, bevy feature, arboard target-gate,
  keyring target-gate). What's *not* yet verified: APK launch on
  AVD/phone, `dirs::data_dir()` Android behaviour for the
  persistence/sync layer.

### Design direction (unchanged)

- **Tone:** Balatro — chunky readable type, theatrical hierarchy,
  satisfying micro-interactions.
- **Palette:** Midnight Purple base + Balatro yellow primary + warm
  magenta secondary.

### Canonical remote

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

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

| Area | Commit | What landed |
|---|---|---|
| Async-pull flake fix | `67c150b` | `pull_failure_sets_error_status` swaps a fixed 5-update budget for a 5-second wall-clock deadline + `yield_now` between pumps. Closes the last v0.19-era flake. |
| Smart window size opt-out | `e1b8766` | New `Settings::disable_smart_default_size: bool` (#[serde(default)]). `solitaire_app::main` reads the flag at startup and skips `apply_smart_default_window_size` registration when set. Settings → Gameplay row toggles it; tooltip notes saved geometry always wins. |
| Shareable badge | `9b065e5` | Stats overlay's Latest-win caption gains `\u{2022} Shareable` when the displayed replay carries a `share_url`. Badge appears on the single-replay caption (no Prev/Next live spawn site yet). |
| Help: M / P / Win-Summary-Enter | `35516d3` | Three rows added to F1 Help → Overlays. Closes coverage drift on post-v0.18 keys. |
| F3 FPS overlay | `690e1d2` | `DiagnosticsHudPlugin` + `FrameTimeDiagnosticsPlugin`. Hidden by default; F3 toggle is not gated by pause/modal state. Smoothed FPS / frame_time. Anchored top-right at `Z_SPLASH + 100`. |
| Android first APK | `fb8b2ac` | `solitaire_app` split into bin + lib (cdylib). `[package.metadata.android]` pins SDK 34 / 26. Bevy gains `android-native-activity`. `arboard` and `keyring`/`keyring-core` target-gated to non-Android. 54 MB APK builds; launch on device not yet verified. |
| Android runbook | `59424a3` | Debian 13 toolchain install, `cargo apk build` invocation, post-sign panic workaround, wired-vs-stubbed table. Fresh-clone runnable. |

## Open punch list

### Carried forward from v0.19.0

- **App icon round.** `Window::icon` not yet wired; no `.icns` /
  `.ico` / Linux hicolor PNG hierarchy. The 11-size icon export
  the v0.19 handoff referenced is *not* currently in
  `artwork/` — re-running `artwork/Icon Export.html` is the
  prerequisite. Half-day task once the PNGs are back in place.
  No cert dependency.

### New — Phase Android (opened by `fb8b2ac` + `59424a3`)

- **APK launch verification on AVD / device.** `adb install` then
  `adb logcat` against the bevy_test AVD. Shakes out any
  Bevy/winit Android-specific runtime bugs not caught by the
  build alone.
- **`dirs::data_dir()` Android port.** Persistence (settings,
  stats, achievements, replays, progress) all route through this
  function. Android sandboxing usually demands `getFilesDir()` via
  JNI. Until verified, the APK may launch but fail to persist
  anything across cold starts.
- **JNI ClipboardManager bridge.** Replaces the Android stub for
  the Stats "Copy share link" toast. `arboard` doesn't ship an
  Android backend, so this is a small custom JNI call.
- **Android Keystore for credentials.** `keyring` is target-gated
  to a stub that returns `KeychainUnavailable`; replace with
  Android Keystore via JNI when sync auth ships on mobile.
- **Google Play Games (gpgs) integration.** Listed in `solitaire_gpgs`
  as a Phase-Android target since Phase 1; now unblocked by the
  build target.
- **Cosmetic `cargo apk build --lib` workaround.** The
  post-sign panic doesn't affect the APK on disk but produces
  noisy stderr. Either upstream a cargo-apk fix or document the
  `--lib` invocation as canonical in the runbook.

### Other small candidates

- **Cut v0.20.0** — the seven commits are a coherent bundle (3
  punch-list closes, 1 docs polish, 1 perf tool, 2 Android arc
  starters). Tag whenever feels right; the Android arc has more
  surface to land before it's "done", but the build-works state
  is a defensible release point.
- **Prev/Next selector chips spawn site.** `9b065e5` notes
  Prev/Next markers exist in `stats_plugin` but no spawn site
  renders them today — the Shareable badge therefore lands on
  the single-replay caption. If/when Prev/Next is plumbed to the
  Stats overlay, the badge will need to follow.

### Process notes (from this round)

- **Async-test starvation pattern (resolved twice now).**
  Auto-save flake (v0.19) and pull-failure flake
  (v0.20-candidates) shared the same root cause: a fixed
  N-update budget for an `AsyncComputeTaskPool` task to surface
  its result, which starves under cargo-test parallelism. The
  wall-clock-bounded loop pattern (`std::thread::yield_now()`
  between pumps, deadline = `Instant::now() + Duration::from_secs(5)`)
  is the canonical fix. Future async-test work should reach for
  this shape on the first commit, not after a flake materialises.
- **Bin → lib + thin shim refactor.** The `solitaire_app` split
  for cargo-apk is a textbook cdylib-as-NativeActivity pattern.
  Worth knowing as a reusable shape for any future Bevy-on-mobile
  project: keep `main.rs` to ≤10 lines that delegate to
  `pub fn run`, put all setup in `lib.rs`, and let the build
  system pick which artifact (`bin` or `cdylib`) it needs.
- **Target-gating defensive defaults.** Three of v0.20-candidates'
  Android-arc commits had to disable a default-on dependency
  (`arboard`, `keyring`, `keyring-core`) for the new target.
  When a future contributor adds a desktop-implicit dependency,
  reaching for `[target.'cfg(not(target_os = "android"))'.dependencies]`
  preemptively is cheaper than rediscovering the gating during
  the next platform port.

## 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.19.0 is tagged on origin; seven commits sit on
top opening the v0.20 cycle (3 punch-list closes + a perf tool +
the Android build target).

State: HEAD at 59424a3 + the v0.20-candidates docs commit on top
(this session). Working tree may carry the doc updates if not yet
committed.

READ FIRST (in order, before doing anything):
  1. SESSION_HANDOFF.md  — this file
  2. CHANGELOG.md        — [Unreleased] holds the v0.20 draft
  3. CLAUDE.md           — unified-3.0 rule set
  4. CLAUDE_SPEC.md      — formal architecture spec
  5. ARCHITECTURE.md     — crate responsibilities + data flow
  6. docs/android/*      — Android setup + build runbook (59424a3)
  7. ~/.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. APK launch verification — `adb install` + `adb logcat` on
     bevy_test AVD or a physical x86_64 device. Shakes out
     runtime bugs the build can't catch.
  B. Phase-Android persistence — port dirs::data_dir() through a
     JNI getFilesDir() bridge so the APK can survive a cold
     start. Largest unblocked Android piece.
  C. App icon — re-run artwork/Icon Export.html, then wire
     Window::icon + generate .icns / .ico. Half-day task. No
     cert dependency.
  D. Cut v0.20.0 — promote [Unreleased] to [0.20.0], tag,
     push. Mechanical close-out; the Android arc has more
     surface to land but the build-works state is a defensible
     release point.

WORKFLOW NOTES:
  - Use the system git config (already correct).
  - 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) — gh auth setup-git wired on
    primary dev box; verify on laptop before first push.

OPEN AT THE START: ask which of A–D. Don't pick unilaterally.
```