Ferrous-Solitaire/SESSION_HANDOFF.md

Ferrous Solitaire — Session Handoff

Last updated: 2026-07-06 — v0.41.0 + v0.41.1 released and verified on a physical Galaxy Fold 7; issue tracker empty except low-priority #130.

---

Current state

• Branch state: master pushed to origin; latest work is the 2026-07-06 arc (PRs #121–#131): scripted repo review, five issues filed and fixed, plugin module splits, two releases.
• Latest tags: v0.41.1 (pile-marker child-resize fix + Android relayout logging) on top of v0.41.0 (consolidated release for everything since v0.39.0). Both released via tag push → CI signed APK; both verified installed on hardware (versionCode 4101).
• Working tree: clean. Local scripts/*.go helpers are intentionally gitignored (.gitignore:43); scripts/watch_deploy.sh is now committed.
• Latest verification: workspace clippy --all-targets -D warnings, full test suite, cargo ndk clippy for aarch64-linux-android, CI release builds green, and an on-device pass on the Fold 7 (fold/unfold layout, safe-area resume, marker fix).
• Issue tracker: #116/#117/#118/#119/#120 all closed 2026-07-06. #130 (transient tableau clip after fold) open at low priority — did not reproduce in repeat testing; v0.41.1's relayout logging is the evidence channel if it recurs.

---

2026-07-06 session summary (v0.40.3 → v0.41.1)

• Scripted repo review (cratemap/todoctx/cargoclip/testfail): clippy clean, tests green, error/SQL policies compliant. Five issues filed and all resolved same-day.
• #116 safe-area re-poll after resume (PR #121): refresh_insets now gates on the poll counter, settles per cycle, and rewrites insets only on change. Verified on Fold 7 — note both Fold screens report identical insets (top=110 bottom=0), so the re-poll path is a no-op on this device.
• #117 Draw-1 recycle (PR #122): unlimited recycling documented as an intentional rules decision (ARCHITECTURE.md "Rules decisions" + draw_one_recycling_is_unlimited_by_design lock-in test). A hard limit would invalidate the difficulty seed catalog and the winnable-deal solver.
• #118 module splits (PRs #124/#125/#127/#128/#129): card, hud, settings, game, and input plugins are now module directories; tests in sibling tests.rs, runtime code split along system boundaries (pub(super) items, mod.rs glob-imports children). Largest runtime file is now card_plugin/sync.rs at 748 lines (was card_plugin.rs at 4,129).
• v0.41.1 pile-marker fix (PR #131): marker outline + "A"/"K" watermark children are re-derived from the layout on every resize — previously spawn-time-sized, rendering as oversized grey slabs on empty foundations after fold/unfold. Found via photo evidence, fixed, re-verified on device.
• Obtainium note: reported "no suitable release" for v0.41.0 even though the anonymous releases API, releases/latest, and the APK download were all verified fine — client-side issue; sideload via adb was used instead.

---

v0.40.0 release (2026-06-25)

Released via tag push → .gitea/workflows/android-release.yml built and signed the arm64-v8a release APK (release keystore, versionCode 4000 / versionName 0.40.0, 29.2 MB) and published it to the Gitea release. Obtainium clients tracking the repo pick it up automatically.

• Release: https://git.aleshym.co/funman300/Ferrous-Solitaire/releases/tag/v0.40.0

PR	Summary
#106	fix(engine): Draw-Three waste fan hit-test now shares the renderer's fan step (card_plugin::waste_fan_step / tableau_col_step). The two had diverged under Android's tighter column spacing (H_GAP_DIVISOR=32), shifting the top fanned waste card's click target onto the card beneath it — so dragging the visible top card played the wrong one. Desktop/web were unaffected (the formulas already coincided there).
#105	test(engine): waste-card draggability regression tests (find_draggable_at picks the waste top with multiple cards and as a lone card).
#108	docs(android): NDK reference updated 26.3.11579264 → 30.0.14904198; noted versions are not load-bearing and build_android_apk.sh auto-discovers the newest NDK/build-tools.

Pre-release validation performed locally this session: workspace clippy/test/build gates; aarch64-linux-android cross-compile + clippy clean (covers the #[cfg(target_os = "android")] paths that host CI never lints); release manifest sanity (solitaire_app/android/AndroidManifest.xml has no version fields so CI injection works; lib_name matches [lib].name); and a full signed local APK proving the build_android_apk.sh packaging pipeline end-to-end.

---

What shipped since v0.39.0

• Browser Bevy canvas route and window.__FERROUS_DEBUG__ automation bridge landed, with Playwright coverage for /play.
• In-place card_game / klondike rewrite phases are complete through the latest follow-up:
  • 5e87358 integrates upstream deps cleanly.
  • ae1ecc8 unifies Suit / Rank with upstream card_game types.
  • d864d98 routes klondike/card imports through solitaire_core.
  • 9bcf13d, 56e3b62, 26f1b00 finish schema-v3 migration coverage, undo/recycle score correctness, and rewrite-plan docs.
• Android keystore wiring, Android build-script hardening, server auth/runtime hardening, and modal safe-area centering have landed.
• CHANGELOG.md has been caught up from v0.34.0 through current unreleased work and committed in 7fe6ac6.
• Matomo analytics was re-reviewed: MatomoClient and AnalyticsPlugin are wired through CoreGamePlugin on non-wasm targets, and targeted tests now cover opt-in client creation, event encoding, buffer trimming, and analytics mode labels.
• Native analytics and Android physical-device validation now have runbooks in docs/analytics-validation.md and docs/ANDROID.md.

---

Historical notes before v0.39.0

See git log and CHANGELOG.md. The changelog now includes v0.34.0 through v0.39.0, plus current unreleased work.

---

What shipped since the last handoff (v0.23.0 → v0.35.1)

v0.34.0 — Android polish + code-quality sweep (2026-05-16/17)

Commit	Summary
9623bde	Wire FiraMono to Android corner label; CardImageSet load tests
980312c	Fix wrong bottom-right suit symbol on JS/QS/KS card assets
04e99a8	Correct Android waste fan overlap and resume layout desync
3bb3ddb	Eliminate panics, fix dismiss hit-test scope, guard home respawn
f8f1f26	Adaptive drop zones, touch event correctness, modal lifecycle guards
1eb4043	Auth-guard avatar serving; atomic write; user_id assertion in merge
69c6e88	Deterministic pile serialization, undo skip, url-encode bytes, merge_at
aa7b0f6	Gate frame-hot ECS systems on resource changes (perf)
6727126	Consolidate APP_DIR_NAME; add #[must_use] on pure fns
a4dfb0c	Differentiate leaderboard opt-in vs opt-out error toasts (M-12)
7fc98f8	WASM: state() and step() return Result, errors throw JS exceptions (CR-6)
ffed6b2	Share Tokio runtime across all network tasks (M-16)
fa84152	Correct Android help hint label → to ! (M-17)
18d7937	Derive Copy for DrawMode; drop redundant .clone() calls (M-18)
132fea9	Use saturating_add for move_count increments (M-19)
0ecc1a9	Add missing derives to AchievementContext (M-20)
2301cc6	Align android_keystore temp extension with cleanup glob (M-21)
2e52f54	Enforce 32-char display_name limit at sync client boundary (M-22)
c8878d6	Fix stale FOCUS_RING colour comment (M-23)
4aafc0a	Name HUD popover Z-layers; replace raw Z arithmetic (M-24)

v0.35.0 — Accessibility + sync reliability (2026-05-18)

Commit	Summary
eb6c93f	Silence B0004 by adding Transform to ModalScrim
6f5cebd	Fire WarningToastEvent on sync pull failure (was InfoToastEvent)
87aec5b	Gate all decorative motion animations under reduce_motion_mode

reduce_motion_mode now gates: score pulse, score floater, streak flourish (hud_plugin), card-shake on rejected move, foundation completion flourish (feedback_anim_plugin). Pattern: gate at the trigger/start system, never at the tick system — if the component isn't inserted, the tick path never runs.

v0.35.1 — Leaderboard bug fixes (2026-05-18)

Commit	Summary
8f86d66	Fix three leaderboard bugs: wrong toast type, stale label, name not synced

Three bugs fixed:

1. Wrong toast type on error — poll_opt_in_task / poll_opt_out_task error branches now fire WarningToastEvent instead of InfoToastEvent.

2. Display name not pushed to server on change — Settings gains leaderboard_opted_in: bool (serde-defaulted false). Set true/false when opt-in/out tasks succeed and persisted to settings.json. handle_display_name_confirm now spawns an opt_in_leaderboard task when already opted in — the server's upsert endpoint updates only display_name without re-opting-in.

3. "Public name" label stale after name change — LeaderboardPublicNameText marker component added to the label node. update_leaderboard_public_name_label system rewrites the text each frame the panel is open; O(0) cost when panel is closed.

5 new regression tests cover all three bugs.

---

Open punch list

1. Physical-device smoke test — PARTIALLY DONE (2026-07-06, Galaxy Fold 7)

v0.41.1 was installed and launched on a physical Fold 7 via adb. Verified: fold/unfold layout on both screens (incl. the #116 resume path and the pile-marker fix), safe-area inset resolution, and app launch/restore basics.

Still unexercised from the device checklist: Draw-Three waste fan tap accuracy (the #106 fix — switch to Draw-Three, drag the visible top waste card ~10×, confirm it plays that card), modal centring on both screens, drag-and-drop across all pile types, kill-and-restore, and the sync token flow. AVD is not a substitute — adb shell input tap doesn't deliver real touch events.

2. Matomo analytics live validation (independent — NOT a release blocker)

Separate, ongoing task unrelated to the Android release. Settings has analytics_enabled, matomo_url, and matomo_site_id; the engine consumes them via AnalyticsPlugin on non-wasm targets. Remaining work is live validation against the deployed Matomo instance. Use docs/analytics-validation.md for the native validation checklist and the current web/WASM decision notes.

---

Architectural notes for next session

• Plugin submodule pattern (2026-07-06 splits): big plugins are module directories: mod.rs holds types/markers/plugin-build and glob-imports the children (use input::*;); children hold pub(super) systems and start with use super::*; plus their own external imports. Tests (tests.rs) may need explicit imports for names no longer used by mod.rs itself.

• Marker child-resize rule: anything spawned as a child of a layout-sized entity (outline frames, watermark text) must be re-derived in on_window_resized too — resizing only the parent sprite leaves children at spawn-time size (the v0.41.1 foldable bug).

• Fold 7 quirks: both screens report identical safe-area insets (top=110, bottom=0), so inset-driven relayout never fires on fold; layout correctness across folds rides entirely on WindowResized. winit 0.30 logs TODO: find a way to notify application of content rect change on resume — see #130 if a stale-width layout ever reproduces; v0.41.1 logs every Android relayout (layout: resize to WxH) for exactly this.

• Reduce-motion pattern: always gate in the start_* / detect_* system (the trigger), not the tick_* system. If the component is never inserted, the tick path never runs. See hud_plugin.rs::detect_score_change and feedback_anim_plugin.rs::start_shake_anim for the canonical pattern.

• Leaderboard server upsert: POST /api/leaderboard/opt-in is idempotent — calling it when already opted in just updates display_name. Safe to call from handle_display_name_confirm without tracking a separate "needs update" flag.

• Messages<T> API (Bevy 0.18.1): write with resource_mut::<Messages<T>>().write(value); read in tests with msgs.get_cursor() + cursor.read(msgs).next().

• Test input-state pitfall: MinimalPlugins has no input-tick system, so ButtonInput::just_pressed state persists across frames unless explicitly cleared with input.release(key); input.clear() between updates.

• /play debug bridge design: play.html runs two independent WASM instances in Promise.all([bootstrap(), init()]). bootstrap() sets window.__FERROUS_DEBUG__ (logic layer via solitaire_wasm.js); init() starts the Bevy canvas. The bridge operates its own SolitaireGame — moves applied through the bridge do NOT affect the Bevy visual game. This is intentional for automation/invariant checking.

• HiDPI Bevy canvas: WindowResolution::default().with_scale_factor_override(1.0) is set in the canvas app. Without this, physical pixels exceed WebGL2's 2048px limit on HiDPI displays, causing an immediate wgpu panic on the first resize event.

• /play-classic vs /play in e2e: smoke.spec.js + gameplay_review.spec.js target /play-classic (DOM-heavy game.html); play_canvas.spec.js targets /play using only the __FERROUS_DEBUG__ bridge (no DOM selectors). cycle_metrics.js supports both via --route play-classic|play.