Ferrous-Solitaire/SESSION_HANDOFF.md

Solitaire Quest — Session Handoff

Last updated: 2026-05-07 — v0.20.0 cut. Two through-lines closed in this cycle: a full Terminal visual-identity port (token system in ui_theme plus downstream chrome migrations across modal scaffold, gameplay-feedback, toasts, and the table / card / splash surfaces) and the Android persistence shim that closes the dirs::data_dir() = None pitfall flagged in CLAUDE.md §10. The Android build target landed earlier in the cycle (fb8b2ac); this session paid down the persistence half so a real APK can survive a cold start. The 24 Stitch-rendered mockups are now in-tree under docs/ui-mockups/; future plugin work diffs against the matching mockup before touching pixels.

Status at pause

• HEAD on origin: the v0.20.0 docs commit (the one that lands this file + CHANGELOG cut). Tag not yet pushed; cut whenever feels right.
• Working tree: clean apart from the still-untracked artwork/ directory (intentional — the card PNGs there are mid-flight for the Terminal aesthetic and committing now would freeze a transitional state).
• Build: cargo clippy --workspace --all-targets -- -D warnings clean.
• Tests: 1176 passing / 0 failing across the workspace. Six new tests this cycle: four ui_theme invariant guards (type / spacing / z-index scales + scaled_duration), one toast-variant-border-mapping pair, and four palette-tracking guards on MARKER_VALID / HINT_PILE_HIGHLIGHT_COLOUR / RIGHT_CLICK_HIGHLIGHT_COLOUR / toast-border distinctness. No known flakes.
• Tags on origin: v0.9.0 through v0.19.0. v0.20.0 not yet tagged.

What shipped in v0.20.0

Terminal visual-identity port

Top-down stack — every commit downstream of the token system reads from it, so swapping the palette is now a one-file edit:

• ui_theme token system (0d477ac). base16-eighties palette, 5-rung type scale, 7-rung 4-multiple spacing scale, 3-step radius, 14-rung z-index hierarchy, full motion budget, 4 invariant-pinning unit tests. Card-shadow alphas pinned to 0 (Terminal achieves depth via 1px borders + tonal layering).
• Modal scaffold already on tokens — ui_modal was ported in the same commit's wake; three stale "loud yellow" / "magenta secondary" doc comments fixed.
• Gameplay feedback → semantic state tokens (ceec4fc). Selection / valid-drop tints route through ACCENT_PRIMARY / STATE_WARNING / STATE_SUCCESS.
• Toasts (a137607). New ToastVariant enum (Info / Warning / Error / Celebration); opaque BG_ELEVATED
  • 1px accent border + bottom-anchor. All ten call sites pass their semantic variant.
• table_plugin chrome (651f406). PILE_MARKER_DEFAULT_COLOUR promoted; cursor_plugin imports it, replacing a "kept in sync" doc comment with a compile- enforced invariant. HINT_PILE_HIGHLIGHT_COLOUR → STATE_WARNING.
• card_plugin chrome (d752870). Drag-elevation shadow routes through CARD_SHADOW_* tokens. RIGHT_CLICK_HIGHLIGHT_COLOUR → STATE_SUCCESS. Stock recycle "↺" text → TEXT_PRIMARY @ 0.7α. Card-face / suit / card-back palette intentionally NOT migrated (artwork dependency — see open-list item below).
• Splash cursor (cdcadda). The signature ▌ cyan glyph (96 px) added above the wordmark, matching the spec.
• Hint-source / dest pairing (9891ae4). input_plugin's source-card tint now matches the destination pile's STATE_WARNING.
• Design system + 24-mockup library (fa7f98a). docs/ui-mockups/design-system.md + 24 Stitch mockups (HTML + PNG) covering every screen plus 9 missing-plugin surfaces.
• card_shadow_params test aligned (1d1543e). Drag-vs- idle shadow assertion loosened to >= to accept the Terminal "no shadow" intent without losing the regression-guard.

Android persistence

• solitaire_data::data_dir shim (4b51e50). New solitaire_data::platform::data_dir() falls through to dirs::data_dir() on desktop and returns the per-app sandbox at /data/data/com.solitairequest.app/files on Android — no JNI needed (package id pinned in [package.metadata.android]). Six solitaire_data callsites + solitaire_engine/assets/user_dir.rs migrated. Settings, stats, achievements, replays, game-state, time-attack sessions, and user themes now persist on Android.

Inherited from earlier in the cycle (pre-session)

• Android build target + APK (fb8b2ac), runbook (59424a3), F3 FPS overlay (690e1d2), Smart Window Size opt-out (e1b8766), Shareable badge (9b065e5), Help cheat-sheet M/P/Enter rows (35516d3), pull_failure_sets_error_status flake fix (67c150b).

Open punch list

Phase Android (build + persistence shipped; runtime gaps remain)

• APK launch verification on AVD / device. adb install then adb logcat against the bevy_test AVD or an x86_64 device. The build works and persistence is wired, but no end-to-end device run has been logged. Shakes out runtime bugs the build + unit tests can't catch.
• JNI ClipboardManager bridge. Replaces the Android stub for the Stats "Copy share link" toast. arboard doesn't ship an Android backend; small custom JNI call.
• Android Keystore for credentials. keyring is target-gated to a stub returning KeychainUnavailable; replace with Android Keystore via JNI when sync auth ships on mobile.
• Google Play Games (gpgs) integration. Listed as a Phase-Android target since Phase 1; now unblocked by the build target.
• Cosmetic cargo apk build --lib workaround. Post-sign panic doesn't affect the APK on disk but produces noisy stderr. Either upstream a cargo-apk fix or document --lib as canonical in the runbook.

Visual-identity follow-ups (opened by v0.20.0's port)

• Card-face / suit / card-back artwork regeneration. The Terminal spec calls for dark #1a1a1a cards with light suit pips (pink for hearts/diamonds, foreground gray for spades/ clubs); the runtime path still renders the legacy white-card PNG artwork. The fallback constants in card_plugin (CARD_FACE_COLOUR, RED_SUIT_COLOUR, BLACK_SUIT_COLOUR, CARD_FACE_COLOUR_RED_CBM, card_back_colour palette) are intentionally unmigrated and should swap in lockstep with the artwork. Largest visible payoff remaining in the visual- identity arc.
• Splash boot-loader richness. The mockup (docs/ui-mockups/splash-mobile.html) calls for a scanline overlay, ✓ lime check log lines, pulsing cursor, ROOT@SOLITAIRE prompt, and a loading bar — none of which v0.20.0's cursor-glyph-only port pulled in. Aesthetic feature, its own commit.
• Replay-overlay redesign. The mockup (docs/ui-mockups/replay-overlay-mobile.html) envisions a much richer surface (terminal ▌replay.tsx header, move log scroll, MOVE 47/87 chip, WIN MOVE callout, status bar) versus the current top banner. Aesthetic feature.
• Toast Warning / Error variants. The new ToastVariant enum has slots for Warning (gold) and Error (pink) but no in-engine event uses them yet (the four current toast events all map to Info or Celebration). Wire when a warning- or error-flavoured toast event materialises.

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/ (current artwork/ holds the reverted Rusty Pixel card PNGs and is intentionally untracked); icon-export needs to be re-run before this item can be picked up. Half-day task once the PNGs are back in place. No cert dependency.

Other small candidates

• Prev/Next selector chips spawn site. v0.19.0's 9b065e5 noted 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, the badge will need to follow.
• Toast queue / immediate unification. The two toast paths (spawn_queued_toast for InfoToastEvent queue; spawn_toast for fire-and-forget) now share visual treatment but remain separate functions because they serve different temporal needs (sequential vs. parallel). If overlap becomes a UX issue, merge into one queue with priority lanes.

Process notes

• Token-port pattern. v0.20.0's chrome-migration commits set a reusable shape for "centralized design system applied across N plugins":
  1. Constants module (ui_theme.rs) is the source of truth.
  2. Const sites that can't call Alpha::with_alpha (not yet const on stable) use a literal RGB matching the token, with a unit test pinning the RGB to the token (e.g. MARKER_VALID, HINT_PILE_HIGHLIGHT_COLOUR, RIGHT_CLICK_HIGHLIGHT_COLOUR).
  3. Cross-plugin duplication (e.g. MARKER_DEFAULT ↔ PILE_MARKER_DEFAULT_COLOUR) collapses to a single promoted const re-exported from one plugin and imported by the other — replaces "kept in sync" doc comments with a compile-time invariant.
  4. Domain colours (suit pips, card faces, lerp helpers) stay as literals with a comment naming the rationale; only UI chrome routes through tokens.
• Audit before migrating wide. Before touching any plugin, grep for the literal pattern (Color::srgb\(|Color::srgba\(| Color::WHITE|Color::BLACK) and classify each hit as domain vs. chrome. Most plugins after the modal scaffold port turned out to be 100 % token-correct already; the audit prevents wasted churn.

Canonical remote

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

Design direction (now Terminal — base16-eighties)

• Tone: retro-terminal / synthwave — flat depth (no box-shadows), monospaced-forward typography (JetBrains Mono / FiraMono), tight 16 px edge margins, 8 px card radius.
• Palette: near-black surface ramp (#151515 / #202020 / #2a2a2a / #353535), cyan primary CTA (#6fc2ef), lime success (#acc267), gold warning (#ddb26f), pink error / suit-red (#fb9fb1), lavender celebration (#e1a3ee), teal info (#12cfc0).
• Two-color suits. Red = #fb9fb1, black = #d0d0d0. Outlined glyphs for diamonds & clubs are always on; the Settings "color-blind mode" toggle only swaps red → cyan.

(Was: Midnight Purple base + Balatro yellow primary + warm magenta. Replaced this cycle.)

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.20.0 just cut on 2026-05-07; CHANGELOG's new
[Unreleased] section is empty pending the next cycle's threads.

State: HEAD on the v0.20.0 docs commit. Tag not pushed yet — last
pushed tag is v0.19.0. Working tree clean apart from the
intentionally-untracked `artwork/`.

READ FIRST (in order, before doing anything):
  1. SESSION_HANDOFF.md  — this file
  2. CHANGELOG.md        — [0.20.0] section is the most recent cut
  3. CLAUDE.md           — unified-3.0 rule set
  4. CLAUDE_SPEC.md      — formal architecture spec
  5. ARCHITECTURE.md     — crate responsibilities + data flow
  6. docs/ui-mockups/    — design system + 24-mockup library
                           (Terminal aesthetic — landed in fa7f98a)
  7. docs/android/*      — Android setup + build runbook
  8. ~/.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. Push v0.20.0 tag — `git tag v0.20.0 && git push --tags`. If
     the player wants the cut formalised before any new work.
  B. APK launch verification — `adb install` + `adb logcat` on
     bevy_test AVD or an x86_64 device. Now that persistence is
     wired (4b51e50), shake out remaining runtime bugs.
  C. Card-face artwork regeneration — generate Terminal-aesthetic
     card PNGs (dark face, light suit pips), then migrate
     CARD_FACE_COLOUR / RED_SUIT_COLOUR / BLACK_SUIT_COLOUR /
     CARD_FACE_COLOUR_RED_CBM in lockstep. Largest visible
     payoff remaining in the visual-identity arc.
  D. Splash boot-loader richness — port the scanline overlay,
     ✓ check log, pulsing cursor, ROOT@SOLITAIRE prompt, and
     loading bar from docs/ui-mockups/splash-mobile.html. Pure
     polish; no behavioural change.
  E. App icon round — re-run artwork/Icon Export.html (the
     export PNGs are not currently in `artwork/`), then wire
     Window::icon + generate .icns / .ico. Half-day task. No
     cert dependency.
  F. JNI ClipboardManager / Keystore bridge — replaces the
     Android stubs for Stats clipboard share + sync auth.

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–F. Don't pick unilaterally.