Ferrous-Solitaire/SESSION_HANDOFF.md

Solitaire Quest — Session Handoff

Last updated: 2026-05-06 (post-v0.19.0) — Tagged + pushed at 6037596. v0.19.0 closes the v0.18.0 punch list (async H-key hint, persistent replay share URLs), expands desktop platform fit (Wayland session support + monitor-aware default window size), polishes the win-celebration and double-click animation paths, and clears two test-flake contributors. A short-lived "Rusty Pixel" pixel-art card theme was prototyped and reverted in the same window.

Status at pause

• HEAD on origin: 6037596 (post-tag commit; the tag itself points at this commit).
• Working tree: modified — CHANGELOG.md and SESSION_HANDOFF.md carry the v0.19.0 promotion + this refresh, ready to commit.
• Build: cargo clippy --workspace --all-targets -- -D warnings clean (verified this session).
• Tests: 1170 passing / 0 failing across the workspace (verified this session). One known flake remains: solitaire_engine::sync_plugin::tests::pull_failure_sets_error_status occasionally fails when cargo-test parallelism starves the AsyncComputeTaskPool within the test's 5-update budget. Same shape as the auto-save flake before v0.19.0's hardening; could be fixed similarly with a wall-clock-bounded loop.
• Tags on origin: v0.9.0 through v0.18.0 (v0.19.0 ready to push once committed).

Where we are

v0.18.0's resume-prompt menu (A–D) is closed:

• A — Tag v0.18.0: shipped at bfcd05f.
• B — Solver-on-AsyncComputeTaskPool for the H-key hint: shipped at 3e11e9e.
• C — Desktop packaging: still gated on artwork + signing certs. Icon export PNGs (11 sizes, 16–1024 px) sit in artwork/ from the v0.18-era export; not yet wired into the Bevy window or assembled into .icns / .ico. App icon is the first natural step.
• D — Persistent share link: shipped at 42d90b1.

The Rusty Pixel theme arc is documented as a sub-history but not part of v0.19.0's content:

Commit	Status
de47511 PNG-format thumbnail support	reverted
17e3112 pixel_art: bool field + nearest-sampling opt-in	reverted
21ec03b bundle Rusty Pixel as embedded:// theme	reverted
aad8bb9 / e41def8 / 0b3140a reverts	landed

The arc remains in commit history for archaeology but the codebase reaches v0.19.0's HEAD identical to where it would be if the arc had never landed.

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.19.0 (2026-05-06)

Area	Commits	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 selected replay. LastSharedReplayUrl deleted.
Auto-save flake fix	91b7605	test_app clears PendingRestoredGame(None) after plugin build; test re-arms the timer in a bounded loop. No production-code change.
Wayland support	b57db01	Adds wayland to Bevy features. winit prefers Wayland when WAYLAND_DISPLAY is set, falls back to X11. Native Wayland surface instead of XWayland frame.
Smart default window size	b57db01	New apply_smart_default_window_size Update system queries PrimaryMonitor and resizes the window to ~70 % of monitor's logical size on the first frame. Skipped when saved geometry was applied.
Win-celebration cleanup	55c235b	Drops the duplicate "You Win" toast that rendered behind the WinSummary modal. Cards-fly-off cascade kept; toast removed.
Double-click reject animation	d7ffb16	Single-card double-clicks with no destination now play the same shake + sound as multi-card stack misses. Both priorities' failure paths converge on one MoveRejectedEvent write.
Double-click animation dedup	6037596	Drops the redundant StateChangedEvent write in end_drag's uncommitted-drag branch; previously raced an in-flight CardAnim and restarted the slide visibly.

Open punch list

Carried forward

• Desktop packaging per ARCHITECTURE.md §17. Eleven icon PNG sizes (16, 24, 32, 48, 64, 96, 128, 192, 256, 512, 1024) exported via artwork/Icon Export.html sit in artwork/ pending wiring. Pending: actual Bevy window-icon hookup, macOS .icns assembly via iconutil, Windows .ico via magick convert, Linux hicolor PNG hierarchy install, AppImage recipe, macOS notarisation cert, Windows Authenticode cert.

Possible next-round candidates

• App icon round — wire the icon into the Bevy window via Window::icon, generate .icns and .ico from the existing PNGs. Half-day task; doesn't depend on signing certs.
• pull_failure_sets_error_status flake fix — same pattern as the auto-save flake. Wall-clock-bounded loop instead of fixed 5-update budget. ~10 lines.
• Settings UI for "open at this size on launch" — once the smart-default-size system is shipping, expose a checkbox to disable it (player who specifically wants 1280×800 every time). Trivial.
• Persistent share link URL on selector caption — surface whether the currently-selected replay has a share_url populated (e.g. "Replay 3 / 8 \u{2022} Shareable") so players know which entries the Copy button can copy.

Process notes (from this round)

• Async port template (worked again): the H-key port followed d489e7a's PendingNewGameSeed shape one-to-one and the second async port required no new infrastructure. Future async ports (e.g. moving try_solve_with_first_move's full-search variant, if it ever surfaces in the picker UI) should follow the same shape.
• Rusty Pixel reverted cleanly: git revert of three contiguous feature commits produced a clean three-revert sequence with no manual conflict resolution. Bisect remains fast over the full v0.19.0 history because the reverts are individual commits, not a squash.
• Defensive event writes pattern: the auto_save_writes_after_30_seconds flake AND the end_drag double-animation bug shared a root cause: defensive MessageWriter writes that originally covered an edge case which no longer holds, but became load-bearing once another system started paying attention to the event. Worth a periodic pass: any event write that doesn't correspond to a real state change is a candidate for removal.

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 just shipped. The next natural item is
desktop-packaging follow-through, starting with the app icon.

State: HEAD at 6037596 + the v0.19.0 docs commit on top (this
session). Tag v0.19.0 points at the docs commit.

READ FIRST (in order, before doing anything):
  1. SESSION_HANDOFF.md  — this file
  2. CHANGELOG.md        — [Unreleased] is empty; [0.19.0] just landed
  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. App icon — wire artwork/icon-{size}.png into Bevy's
     Window::icon, generate .icns + .ico, drop into Linux
     hicolor hierarchy. Half-day task. No cert dependency.
  B. Desktop packaging continued — AppImage recipe, .desktop
     file, install scripts. Larger task; unlocks distro
     packaging. No cert dependency.
  C. macOS / Windows signing cert acquisition — needs user
     action; agent can't drive.
  D. `pull_failure_sets_error_status` flake fix — small, well-
     scoped. Same pattern as the v0.19.0 auto-save flake fix.

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 is already
    wired on this machine.

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