Ferrous-Solitaire/SESSION_HANDOFF.md

# Solitaire Quest — Session Handoff

**Last updated:** 2026-05-08 — v0.20.0 cut and tagged at `41a009a`,
all post-cut commits pushed to origin (HEAD = `dd101b3`), working
tree clean.
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, the post-tag work split
into two arcs: (1) splash boot-screen port + replay-overlay
banner enrichments + desktop-adaptation spec — closing Resume-prompt
Options B and C (see "Since the v0.20.0 cut" entries below); and
(2) **the card-face artwork regeneration arc — Option D, closed
2026-05-08** — full Terminal cards rendering on every face, plus
three follow-up fixes that surfaced during sign-off (default-theme
SVG override, table backgrounds, top-bar overlap), plus a
glyph-orientation tweak (no 180° inverted-corner rotation).

## Status at pause

- **HEAD locally:** see `git rev-parse HEAD`. Most recent narrative
  entry below names the latest substantive commit; this status line
  intentionally avoids hard-coding the SHA so a docs-only edit
  doesn't immediately stale the handoff.
- **HEAD on origin:** matches local. All post-cut commits pushed
  through `dd101b3`. Decide whether to roll the post-tag work
  into v0.20.1 / v0.21.0-candidates the next time a release is cut.
- **Working tree:** clean. No WIP outstanding.
- **`artwork/` directory:** still untracked. Intentional.
- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
  clean.
- **Tests:** **1184 passing / 0 failing** across the workspace.
  Net delta from the 1180 baseline: splash polish added two
  (`build_scanline_image_has_expected_2x2_rgba_bytes`,
  `scanline_overlay_spawns_and_fades_with_splash`); the
  card-face migration added one (`card_face_svg_pin` integration
  test) and consolidated two (`face_colour` CBM tests folded
  into `text_colour` CBM tests, net −2 then +1 from pin);
  call it +4 net.
- **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).
  *Open in "Visual-identity follow-ups" below.*
- Pulsing cursor on the "ready_" line (would fight the global
  fade timeline). *Open in "Visual-identity follow-ups" below.*
- "RUSTY SOLITAIRE" wordmark from the mockup (the actual product
  is "Solitaire Quest"; the mockup leaked the repo name). *Closed
  — the in-engine wordmark stays "Solitaire Quest".*

### `c84d9f4` `feat(engine): scrub fill bar + per-frame updater for replay overlay`

Closes the WIP described in the prior handoff. Adds the 1 px cyan
scrub bar called for in `docs/ui-mockups/replay-overlay-mobile.html`:
a track in `BORDER_SUBTLE` spans the bottom edge of the banner and
the cyan `ACCENT_PRIMARY` fill mirrors `cursor / total` via a new
`ReplayOverlayScrubFill` component + `update_scrub_fill` system.
The pure `scrub_pct` helper is shared between the spawn path
(initial fill width) and the per-frame updater so the first paint
already reflects state instead of popping `0 → cursor` on the
first tick — same shape as the existing `format_progress` /
`update_progress_text` split. Two new tests cover the four corners
of `scrub_pct` and an end-to-end drive of `ReplayPlaybackState`
asserting `Node.width` on the unique scrub-fill entity. Same
change-detection guard as the text updaters, so an idle replay
leaves the node untouched.

Header text treatment (closed by `6204db8` immediately below),
move-log scroll, MOVE chip, and WIN MOVE callout from the same
mockup are still open — separate commits.

### `6204db8` `feat(engine): port replay banner label to ▌ cursor-block treatment`

Aligns the replay overlay's headline with the splash boot-screen
idiom landed in `cacb19c`: `Replay` → `▌ replay` and
`Replay complete` → `▌ replay complete`. The cursor block (`▌`,
U+258C) prefixed to a lowercased label reads as a Terminal output
line rather than a generic UI title, tightening the family
resemblance between the two top-level overlay surfaces. Pure
text-content change; no behavioural shift, no new components, no
new systems.

**Mockup deviation (intentional):** the source mockup string in
`docs/ui-mockups/replay-overlay-mobile.html` is `▌replay.tsx`. The
`.tsx` is a prototyping leak — Stitch renders in React, so the
mockup author reached for a familiar filename — and was dropped
for the in-engine version since the codebase is Rust. The `▌` +
lowercase pattern is what reads as a Terminal-output-line; the
extension is incidental. (Same shape as the "RUSTY SOLITAIRE"
wordmark deviation noted under `cacb19c` — the mockup leaked the
repo name; the actual product is "Solitaire Quest".)

### `54005d5` `feat(engine): add GAME #YYYY-DDD caption beneath the replay headline`

Adds the right-anchored game-identifier piece of the replay-overlay
mockup, adapted to live *under* the existing "▌ replay" headline as
a `TYPE_CAPTION` (11 px) / `TEXT_SECONDARY` subtitle. Format is
`GAME #{year}-{ordinal:03}` (e.g. `GAME #2026-122` for a replay
recorded 2026-05-02) — year + chrono ordinal gives a compact,
monotonically-increasing identifier matching the mockup's
`GAME #2024-127` motif. New `ReplayOverlayGameCaption` marker, new
pure helper `format_game_caption(state) -> Option<String>` (None
for Inactive / Completed since the replay is consumed in those
branches; spawn-time fall-through to empty string).

**Layout impact:** `BANNER_HEIGHT` bumped 48 → 60 px so the new
left column (headline + 2 px gap + caption ≈ 39 px content) fits
under the scrub bar with room to spare. +12 px banner mass is the
deliberate cost of the new content; no other plugin observes
`BANNER_HEIGHT` so the change is local.

Two new tests (1180 → 1182): `format_game_caption_covers_state_corners`
pins the three branches plus the zero-pad-to-3-digits invariant
for early-January ordinals; `overlay_game_caption_shows_replay_date`
drives `ReplayPlaybackState` end-to-end.

### `e080b49` `feat(engine): restyle replay progress text as Terminal MOVE chip`

Closes the centre-text half of the replay-overlay enrichments. The
plain "Move N of M" text becomes a 1px `ACCENT_PRIMARY`-bordered
chip containing "MOVE N/M" — uppercase + slash separator reads as
a Terminal output line and matches the floating-chip motif in
`docs/ui-mockups/replay-overlay-mobile.html`. The chip lives
in-banner rather than floating above the focused card (the
screen-takeover treatment that requires plumbing cursor → card
identity remains deferred).

**Implementation note:** `BorderColor` in Bevy 0.18 is a per-side
struct, not a tuple — `BorderColor::all(ACCENT_PRIMARY)` is the
correct constructor. Worth pinning for next time we touch a
border-painted UI surface. The `ReplayOverlayProgressText` marker
stays on the inner Text rather than the new chip Node so
`update_progress_text` keeps repainting unchanged — a deliberate
"markers belong on the entity that updates change" choice.

Test count unchanged (1182); `overlay_progress_text_reflects_cursor`
swapped its assertion from "Move 5 of 10" to "MOVE 5/10".

This pair (`54005d5` + `e080b49`) closes Option C from the
SESSION_HANDOFF Resume prompt's banner-local enrichments. Floating-
chip-above-focused-card and the full screen-takeover redesign
remain — both data-layer or cross-plugin and intentionally still
open.

### `29136d8` `feat(engine): add pulsing trailing cursor to splash "▌ ready_" line`

Closes the cursor-pulse half of the splash polish arc deferred in
`cacb19c`. The "▌ ready_" line now ends with a 6×12 px cyan Node
that pulses on a 1 s sine cadence, multiplied with the global
splash fade timeline so the cursor never reaches full alpha while
the rest of the splash is still fading in.

**The "multiply, don't override" pattern.** Two systems write the
same `BackgroundColor` per frame: `advance_splash` writes the
global-fade alpha, `pulse_splash_cursor` overwrites with
`global_alpha × pulse_factor`. Both derive from `SplashAge` on the
root, so the writes are commensurate — the second one isn't
"fighting" the first, just refining it. This is the cleanest fix
for the "fight the global fade timeline" warning the original
`cacb19c` skip note flagged.

**Defensive division guard.** `cursor_pulse_factor(age, period, min)`
short-circuits to `1.0` when `period <= 0.0` so a future
misconfiguration produces a steady cursor rather than NaN
propagation (NaN in alpha = invisible UI, hard to debug). Worth
mirroring on every trig/division helper, not just this one.

One new test (1182 → 1183): `cursor_pulse_factor_corners` pins the
peak (factor = 1 at age = period / 4), trough (factor = min at age =
period × 3 / 4), and the zero/negative-period guard.

### `a27cf5a` `feat(engine): add tiled scanline overlay to splash`

Closes the scanline half of the splash polish arc. A fullscreen
`ImageNode` tiles a runtime-generated 2×2 RGBA8 texture over the
splash content — top row transparent, bottom row `#1a1a1a` at
~30 % alpha — producing the 1 px-pitch horizontal scanline pattern
called for in `docs/ui-mockups/splash-mobile.html`.

**Texture-α × tint-α composite for fade integration.** The 30 %
alpha is baked into the texture pixels, not the `ImageNode.color`
tint. `advance_splash`'s new third query writes
`(1, 1, 1, global_alpha)` into the tint each tick; the GPU
multiplies texture-α by tint-α, so the visible composite is
`0.3 × global_alpha`. Cleaner than building a "multiplicative
fadable" abstraction in the ECS — the GPU already does this
multiplication for free.

**Bevy 0.18 API surprises (worth pinning):**
- `RenderAssetUsages` re-exports under `bevy::asset::`, not
  `bevy::render::render_asset::`. Type name unchanged; module
  path moved.
- `TextureFormat::pixel_size()` returns `Result<usize, _>` rather
  than the bare `usize` you'd expect for a static format query.
  Annoying enough that the `debug_assert_eq!` against the buffer
  length just hard-codes the `2 × 2 × 4 = 16` literal.

Headless test fixture now also `init_resource::<Assets<Image>>()`
since `MinimalPlugins` doesn't pull `AssetPlugin` — same pattern
`settings_plugin::tests` already used. Without it, the
`Option<ResMut<Assets<Image>>>` parameter on `spawn_splash` would
fall through and the scanline overlay would silently skip,
defeating the new tests.

Two new tests (1183 → 1185):
`build_scanline_image_has_expected_2x2_rgba_bytes` locks the
texture pixels literally so a future tweak can't drift the
appearance silently; `scanline_overlay_spawns_and_fades_with_splash`
asserts spawn placement under `SplashRoot` and the new
fade-images branch's correctness end-to-end.

This pair (`29136d8` + `a27cf5a`) closes Option B from the
SESSION_HANDOFF Resume prompt — both splash polish pieces now
shipped.

### `5623368`…`dd101b3` — Option D card-face migration arc

Closed 2026-05-08 across nine commits. The full Terminal card
artwork now renders end-to-end. Detail breakdown lives in the
"Visual-identity follow-ups" punch-list entry below; the short
version:

- Migration plan + pipeline tooling: `5623368` (plan doc),
  `3a4bb63` (single-card PoC proving the `usvg`/`resvg` pipeline
  at per-card grain), `babe5cc` (full
  `solitaire_engine/examples/card_face_generator.rs` example
  emitting 52 faces + 5 backs into `assets/cards/`), `48b28d2`
  (the `card_face_svg_pin` integration test pinning rasteriser
  output via inline FNV-1a hashing of raw RGBA8 bytes — the
  pin's bootstrap pattern, "empty `EXPECTED` → run → paste",
  is the maintenance interface for future intentional changes).
- Lockstep step 4+5: `e8bf9d7`. New PNG bytes + the 5
  `card_plugin` constants (`CARD_FACE_COLOUR`,
  `RED_SUIT_COLOUR`, `BLACK_SUIT_COLOUR`,
  `CARD_FACE_COLOUR_RED_CBM` → `RED_SUIT_COLOUR_CBM`,
  `card_back_colour`) + signature shifts in one commit.
  `face_colour` deleted — Terminal face is uniformly
  `CARD_FACE_COLOUR` regardless of CBM, so the function
  collapsed to a constant. `text_colour` gained a
  `color_blind: bool` parameter (red→cyan suit-glyph swap when
  CBM is on). Four `face_colour` CBM tests folded into two
  `text_colour` CBM tests in lockstep.
- Three follow-ups that surfaced during sign-off, all from the
  same "fallback path the migration walked past" pattern:
  `a14200a` regenerated the embedded **default-theme SVGs** at
  `solitaire_engine/assets/themes/default/*.svg`; those bytes
  `include_bytes!()`-embed into the binary and override
  `assets/cards/*.png` at startup, so the PNG migration alone
  didn't change what production rendered. `8719f77`
  regenerated `assets/backgrounds/bg_*.png` to flat Terminal
  near-black (5 solid-colour PNGs via a new
  `solitaire_engine/examples/background_generator.rs` example).
  `ae84dc1` cleared the **top-bar overlap** at portrait/narrow
  window widths by swapping the action-button row's hardcoded
  `font_size: 16.0` to `TYPE_BODY` (a typography-migration
  miss) and stepping horizontal padding from `VAL_SPACE_3`
  to `VAL_SPACE_2`.
- Glyph-rendering fix: `af414b6`. The bundled `FiraMono`
  doesn't carry usable U+2660-2666 glyphs at the requested
  size — `usvg` was silently substituting tiny "tofu" marks.
  Switched suit glyphs from `<text>` elements to inline SVG
  `<path>` elements via a new `suit_path_d` helper. Path-based
  rendering bypasses the font system entirely; same bytes on
  every machine, no fontdb dependency, no substitution risk.
  Same path data renders correctly whether filled (♥ ♠) or
  outlined (♦ ♣ — the always-on color-blind glyph
  differentiation).
- Glyph-orientation tweak: `dd101b3`. Removed the 180° rotation
  from the bottom-right large suit glyph at user request. Both
  glyphs now render upright. `design-system.md` § Game Cards
  line 220 updated in lockstep — the deliberate deviation from
  the traditional inverted-corner-indicator convention is
  documented in the spec, not just the code.

The pin test fired exactly twice during this arc (once for the
text→path switch, once for the unrotation) and rebaselined
cleanly each time via the empty-then-paste pattern. The 5
`back_*` hashes stayed identical across both rebaselines —
secondary signal that the FNV-1a fingerprinting is purely
deterministic on rasteriser output.

This arc closes Option D from the SESSION_HANDOFF Resume prompt
and effectively completes the Terminal visual-identity port —
only the toast warning/error variant slots remain wired-but-
unused.

## 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

### 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 — closed
  2026-05-08 by the commit chain `5623368` → `dd101b3`.* The
  Terminal spec called for dark `#1a1a1a` cards with light suit
  pips (pink for hearts/diamonds, foreground gray for spades/
  clubs). Closed across nine commits over two arcs:
  - **Plan + tooling (`5623368`–`48b28d2`):** migration plan
    doc, single-card PoC, full `card_face_generator` example
    (52 faces + 5 backs into `assets/cards/`), and the
    `card_face_svg_pin` integration test pinning rasteriser
    output via FNV-1a so future `usvg`/`resvg` upgrades surface
    as test failures rather than silent visual drift.
  - **Lockstep step 4+5 (`e8bf9d7`):** PNGs + the 5 `card_plugin`
    constants + signature shifts in one commit.
    `CARD_FACE_COLOUR_RED_CBM` renamed to `RED_SUIT_COLOUR_CBM`
    and repurposed from a face-tint to a suit-glyph swap (the
    Terminal face is uniform `CARD_FACE_COLOUR` regardless of
    CBM; CBM only swaps red suits to cyan in the glyph itself).
    `face_colour` deleted, `text_colour` gained a `color_blind`
    parameter.
  - **Three follow-ups that surfaced during sign-off:**
    `a14200a` regenerated the **default-theme SVGs** at
    `solitaire_engine/assets/themes/default/*.svg` — those
    `include_bytes!()`-embed into the binary and override
    `assets/cards/*.png` at runtime, so the PNG migration alone
    didn't change what production rendered. `8719f77`
    regenerated `assets/backgrounds/bg_*.png` to flat Terminal
    near-black (5 solid-colour PNGs via a new
    `background_generator` example). `ae84dc1` cleared the
    **top-bar overlap** at portrait/narrow window widths by
    swapping the action-button row's hardcoded `font_size: 16.0`
    to `TYPE_BODY` and stepping horizontal padding from
    `VAL_SPACE_3` to `VAL_SPACE_2`.
  - **Glyph-rendering fix (`af414b6`):** suit glyphs render as
    inline SVG paths (not `<text>`) because the bundled
    `FiraMono` doesn't carry usable U+2660-2666 at the
    requested size — `usvg` was silently substituting tiny
    "tofu" marks. Path-based rendering bypasses the font system
    entirely; same bytes on every machine. The pin test
    rebaselined cleanly via the empty-then-paste pattern.
  - **Glyph-orientation tweak (`dd101b3`):** removed the 180°
    rotation from the bottom-right large suit glyph at user
    request — both glyphs now render in the same upright
    orientation. `design-system.md` § Game Cards line 220
    updated in lockstep to document the deliberate deviation
    from the traditional inverted-corner-indicator convention.
- *Splash boot-loader scanline overlay — closed by `a27cf5a`.*
  Runtime-generated 2 × 2 RGBA8 texture tiled via
  `NodeImageMode::Tiled`; per-pixel alpha × tint alpha gives
  multiplicative fade integration without new abstractions.
- *Splash cursor pulse — closed by `29136d8`.* Trailing 6 × 12 px
  cyan Node, sine-pulsed, multiplied with the global splash fade
  (the "multiply, don't override" pattern that resolves the
  original `cacb19c` skip-rationale).
- **Replay-overlay enrichments beyond the scrub bar.** Banner-local
  pieces of the mockup (`docs/ui-mockups/replay-overlay-mobile.html`)
  all shipped: scrub bar (`c84d9f4`), `▌ replay` cursor-block label
  (`6204db8`), `GAME #YYYY-DDD` caption (`54005d5`), `MOVE N/M`
  chip restyle (`e080b49`). What's still open are the cross-plugin
  / data-layer pieces: a `MOVE N/M` chip *floating above the
  focused card* during playback (would need to thread the cursor
  through to the card layer — `update_progress_text` writes the
  banner chip but the card-position lookup belongs in `card_plugin`).
  The full mockup's screen-takeover treatment — mini-tableau
  preview, playback controls, move-log scroll, WIN MOVE marker on
  the scrub bar — is a multi-session redesign with
  data-layer impact (move-log scroller; the WIN MOVE marker
  needs a `win_move_index` field on `Replay` that doesn't yet
  exist). 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 has unpushed post-cut commits**
— run `git log --oneline origin/master..HEAD` for the live list;
`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; the post-cut work
through dd101b3 is pushed to origin (Options B, C, D all closed).
Run `git log --oneline 41a009a..HEAD` to see what landed since the
tag — substantives: desktop-adaptation spec, splash boot-screen
port, replay-overlay banner enrichments, and the full card-face
artwork arc (52 faces + 5 backs as Terminal SVG-rasterised PNGs,
default-theme SVGs in lockstep, table backgrounds flattened,
top-bar layout fix, glyph orientation upright).

State: HEAD locally — see `git rev-parse HEAD`. Working tree is
clean. All workspace tests pass (~1180+; check with
`cargo test --workspace`), 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. 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.
  B. *Closed by `29136d8` + `a27cf5a`.* Both splash polish
     pieces shipped (cursor pulse + scanline overlay). No further
     splash work pending unless a new mockup detail surfaces.
  C. *Closed by `54005d5` + `e080b49`.* Banner-local replay-overlay
     pieces all shipped (scrub bar, ▌ label, GAME caption, MOVE
     chip). Remaining are cross-plugin (floating MOVE chip above
     the focused card — needs cursor → card-position plumbing) or
     multi-session (full screen-takeover redesign — move-log
     scroll, mini tableau, WIN MOVE marker, data-layer impact).
     Either belongs in its own decision tree the next time replay
     work surfaces.
  D. *Closed 2026-05-08 by `5623368`…`dd101b3`.* The full
     card-face / suit / card-back / default-theme / table-
     background / top-bar / glyph-orientation arc landed across
     nine commits. Terminal cards rendering on every face (dark
     `#1a1a1a` background, pink/gray suit glyphs as inline SVG
     paths, scanline-pattern cyan-accent backs); both rendering
     paths (`assets/cards/*.png` and the bundled-default theme
     SVGs at `solitaire_engine/assets/themes/default/*.svg`) in
     lockstep; pin test (`card_face_svg_pin`) guards against
     future rasteriser drift. Visual-identity arc effectively
     complete — only the toast warning/error variant slots
     remain wired-but-unused.
  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.
```