# Solitaire Quest — Session Handoff **Last updated:** 2026-05-07 — v0.20.0 cut and tagged at `41a009a`, two post-cut commits sit on top of the tag, and a constructive `replay_overlay` WIP is checked out in the working tree. The cut itself shipped two through-lines: a full **Terminal visual-identity port** (token system, modal scaffold, gameplay-feedback, toasts, table / card chrome, splash cursor) and the **Android persistence shim** that closes the `dirs::data_dir() = None` pitfall flagged in CLAUDE.md §10. Since the cut, two more pieces landed: the rules- based desktop-adaptation spec (closes the spec gap exposed when we noticed 23 of 24 mockups were mobile-only) and the splash boot- screen port (full mockup-spec splash with header, boot log, progress bar, palette swatches, version footer, ~496 LOC of `splash_plugin.rs` rewrite + `SplashFadable` scaffold refactor). ## Status at pause - **HEAD locally:** `cacb19c` (splash boot-screen port). - **HEAD on origin:** `41a009a` (the v0.20.0 cut). Local master is **2 commits ahead of origin** — `39b8496` (desktop-adaptation spec) and `cacb19c` are not yet pushed. Decide whether to roll these into v0.20.1 / v0.21.0-candidates before pushing. - **Working tree:** dirty — `solitaire_engine/src/replay_overlay.rs` carries a constructive WIP for a 1px scrub-bar at the bottom edge of the replay banner (~120 LOC). Compiles with one missing piece: `update_scrub_fill` is referenced in the plugin's `add_systems` chain but the function body was never written. **The working tree does not compile. HEAD itself is clean** (verified by stashing the WIP and running `cargo check -p solitaire_engine` against the committed state — passes). Resume by writing the missing function (see "Open punch list → replay_overlay scrub bar"). - **`artwork/` directory:** still untracked. Intentional. - **Build at HEAD (WIP stashed):** `cargo clippy --workspace --all-targets -- -D warnings` clean. - **Tests at HEAD (WIP stashed):** **1178 passing / 0 failing** across the workspace. Up from 1176 at the v0.20.0 cut: the splash boot-screen port adds two new tests (`splash_renders_terminal_boot_screen_content` and `fadables_start_transparent_and_reach_full_alpha`). - **Tags on origin:** `v0.9.0` through `v0.20.0`. v0.20.0 is on `41a009a`. ## Since the v0.20.0 cut (un-pushed) ### `39b8496` `docs(ui): add Terminal desktop-adaptation spec` `docs/ui-mockups/desktop-adaptation.md` — 283 lines covering viewport assumptions, seven universal adaptation rules, and per- screen geometry rules for the priority surfaces (Game Table, Win Summary, Settings, Help, Pause, Home, Splash, Stats, and the modal-pattern screens Profile / Achievements / Theme Picker / Daily Challenge). Closes the spec gap — 23 of 24 mockups were mobile-only, but the v0.20.0 token-port pass was already layout- agnostic so nothing shipped broken. The spec matters for *next* ports. **Why rules > visual mockups for this gap:** Stitch's `generate_variants` API timed out on the layout-only adaptation prompt (server-side flake, not a prompt-shape issue — confirmed by polling `list_screens` with no new variant landing). A markdown rules file applies to every screen including the 9 missing-plugin surfaces (splash, challenge, time-attack, weekly-goals, leaderboard, sync, level-up, replay-overlay, radial-menu) that aren't in the Stitch project at all. It's also referenceable from code comments and commit messages without loading an image. ### `cacb19c` `feat(engine): port the splash to the Terminal boot-screen treatment` Implements the full mockup-spec splash from `docs/ui-mockups/splash-mobile.html` plus the desktop adaptation rules: - **Header**: cursor block (96 px `▌`), wordmark ("Solitaire Quest"), 192 px divider, "TERMINAL EDITION" subtitle. - **Boot log**: three ✓ check rows (`assets loaded`, `theme: terminal`, `progress restored`) + a `▌ ready_` line. Capped at 480 px width on desktop (else 70 % viewport). - **Progress bar**: 1 px track (`BORDER_SUBTLE`) with a 100 %- width cyan (`ACCENT_PRIMARY`) fill + `DONE · 247 ASSETS` caption. Capped at 720 px on desktop (else 80 %). - **Footer**: `BASE16-EIGHTIES` label, eight palette swatches (12 × 12 px each — one per named token in the design system), version line. **Refactored the alpha-fade scaffold** from per-marker queries (`SplashTitle` / `SplashSubtitle` / `SplashCursor`) to a single `SplashFadable { base_color: Color }` + `SplashFadableBg` variant. ~15 fadable elements share one global query each; adding more is one component-attach, not three new query types. **Skipped, with rationale captured in the commit:** - Scanline overlay (needs a tiled-pattern asset or custom shader). - Pulsing cursor on the "ready_" line (would fight the global fade timeline). - "RUSTY SOLITAIRE" wordmark from the mockup (the actual product is "Solitaire Quest"; the mockup leaked the repo name). ## What shipped in v0.20.0 (frozen at `41a009a`) ### 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. *Subsequently expanded post-cut by `cacb19c` into the full boot-screen treatment.* - **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 ### In flight (resume here first) - **`replay_overlay` scrub bar.** The working tree carries a WIP that adds a 1px-tall scrub bar at the bottom edge of the replay banner — track in `BORDER_SUBTLE`, fill in `ACCENT_PRIMARY`, width = `cursor / total` of the bar. The banner has been restructured from a single row (`flex-row`, `justify-between`) to a column with the existing content row + the new scrub bar. New marker `ReplayOverlayScrubFill`, `scrub_pct` helper function, and a reference to a system `update_scrub_fill` in the plugin's `add_systems` chain — but **the function body was never written**, so the working tree doesn't compile. Resume by: 1. Writing `fn update_scrub_fill(state, mut q)` that reads `ReplayPlaybackState` and writes `Node::width = Val::Percent(scrub_pct(&state))` on every `ReplayOverlayScrubFill` entity, with a `state.is_changed()` early-exit (mirrors the existing `update_progress_text` shape). 2. Adding two tests: scrub fill at 0 % when cursor = 0; scrub fill at 100 % on `Completed`. 3. Commit message draft already implied by the WIP scope: `feat(engine): scrub-bar fill on the replay overlay`. WIP-only mockup elements deliberately left out: WIN MOVE marker (needs a `win_move_index` data-layer field that doesn't exist), 0/25/50/75/100 % notch labels (aesthetic-only), full playback toolbar / move-log / mini tableau (screen-takeover redesign, not a banner enhancement). ### 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 scanline overlay.** `cacb19c` shipped the rest of the boot screen but skipped the scanline overlay (1px lines at 2 px pitch in `#1a1a1a` over the whole splash, 30 % opacity). Needs a tiled-pattern asset (a 2 × 2 px PNG) or a custom shader. Pure aesthetic, no behaviour change. - **Splash cursor pulse.** The "ready_" line's mockup pulses a cyan 6 × 12 px block at the end of the text. `cacb19c` skipped this because a per-element pulse fights the global `SplashFadable` fade timeline. Either layer the pulse on top of the fade (multiply alphas) or accept the static cursor. - **Replay-overlay full redesign.** The scrub-bar WIP above is the *minimum* of the mockup. The full mockup (`docs/ui-mockups/replay-overlay-mobile.html`) is a screen- takeover with a mini-tableau preview, playback controls, move-log scroll, status bar, and a WIN MOVE marker. That's a multi-session redesign with data-layer impact (move log scroller, win-move detection). The current banner-overlay behaviour is intentionally preserved for now. - **Toast Warning / Error variants.** The `ToastVariant` enum has slots for `Warning` (gold) and `Error` (pink) but no in-engine event uses them yet. 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 - **The desktop-adaptation spec is the canonical reference for geometry decisions** when porting any future plugin. Read `docs/ui-mockups/desktop-adaptation.md` first; apply the universal rules to every surface; consult the per-screen table for the priority surfaces. The 9 missing-plugin screens (splash now ported; eight remaining) inherit the universal rules without dedicated guidance. - **Stitch `generate_variants` is unreliable for layout-only adaptation prompts** as of 2026-05-07. The first call timed out and no variant ever landed in `list_screens`. If a future session wants visual desktop mockups, prefer `generate_screen_from_text` with a fresh narrow prompt per screen rather than `generate_variants` against existing mobile screens. - **Token-port pattern.** v0.20.0's chrome-migration commits set a reusable shape for "centralised 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. - **`SplashFadable` scaffolding pattern** (introduced in `cacb19c`). Any future overlay that needs to fade `N >> 3` elements together should follow the same shape: one tiny marker carrying the full-alpha base colour, one global query that lerps every marker's alpha each frame, no per-element query plumbing. Cleanly outscales the `Without, Without` query exclusion pattern that the old splash was hitting at three siblings. ### Canonical remote `github.com/funman300/Rusty_Solitaire` is the canonical repo. Always push there. **Local master is currently 2 commits ahead of origin** — `git push` is the next durability step (or roll the post-cut commits into v0.20.1). ### Design direction (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. ## Resume prompt ``` You are a senior Rust + Bevy developer working on Solitaire Quest. Working directory: . Branch: master. v0.20.0 is tagged at 41a009a; two post-cut commits sit on top locally (39b8496 desktop-adaptation spec, cacb19c splash boot-screen port) — these have NOT been pushed yet. State: HEAD locally at cacb19c. Working tree is dirty: solitaire_engine/src/replay_overlay.rs carries a constructive WIP for a 1px scrub-bar at the bottom of the replay banner. The WIP references a function `update_scrub_fill` in the plugin's add_systems chain but the body was never written — `cargo check` fails on the working tree until the function is added. HEAD itself (WIP stashed) is clean: 1178 tests pass, clippy clean. 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 + desktop-adaptation.md (the rules-based companion to the mockups; read this before any plugin port) 7. docs/android/* — Android setup + build runbook 8. ~/.claude/projects//memory/MEMORY.md — saved feedback / project context (machine-local; may be missing on a fresh machine) DECISION TO ASK THE PLAYER FIRST: A. Finish the replay_overlay scrub-bar WIP. Write `update_scrub_fill`, add tests, commit. Tractable in one session; the WIP is fully scoped (see SESSION_HANDOFF.md → "In flight"). B. Push the post-cut commits to origin. Either as-is on master or rolled into a v0.20.1 cut (CHANGELOG entry + tag). Mechanical, but local master diverges from origin until done. 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. Multi-session. D. Splash scanline overlay + cursor pulse. The two pieces of the mockup `cacb19c` skipped. Pure polish; no behaviour 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. APK launch verification on AVD / device + the JNI bridges it would shake out (ClipboardManager, Keystore). 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. ```