Ferrous-Solitaire/SESSION_HANDOFF.md

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<X>, Without<Y> 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: <Rusty_Solitaire clone path on this machine>.
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/<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. 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.