Ferrous Solitaire — Session Handoff

Last updated: 2026-06-09 — card_game rewrite follow-up complete; changelog catch-up in progress; analytics follow-up tests added.

Current state

HEAD: 6193d31 (fix(engine): centre modal cards within usable area (status-bar + gesture-bar))
Latest tag: v0.39.0
Working tree: documentation and analytics-test follow-up changes pending (CHANGELOG.md, SESSION_HANDOFF.md, docs/card-game-integration.md, solitaire_data/src/matomo_client.rs, solitaire_engine/src/analytics_plugin.rs)
Latest verification in this follow-up: cargo test -p solitaire_core; Matomo client/plugin targeted tests.
Full previous gate: Claude reported recent card_game work pushed to origin and cargo test / clippy gates passing before the changelog follow-up.

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; verify it before committing because it was started by a rate-limited Claude workflow and then manually tightened.
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.

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:

Wrong toast type on error — poll_opt_in_task / poll_opt_out_task error branches now fire WarningToastEvent instead of InfoToastEvent.
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.
"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. Android APK launch verification (Option A)

Physical device test: install the latest APK on a real Android device (not AVD), confirm:

App launches without crash
Safe area insets arrive and shift HUD correctly after ~3 frames
All modal Done buttons are above the gesture bar
Drag-and-drop works on all pile types
Leaderboard panel opens and the "Public name" label updates correctly after using "Set Name"

This has never been gated in CI. AVD adb shell input tap doesn't deliver real touch events, so physical-device smoke testing is the only gate.

2. Matomo analytics live validation

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:

Configure matomo_url and opt in through Settings.
Play a short session that starts a game, wins or forfeits, and unlocks or verifies an achievement event path if practical.
Confirm Matomo receives Game / Start, Game / Won or Game / Forfeit, and any achievement events.
Decide whether the web/WASM route should eventually use browser-side tracking, since the native AnalyticsPlugin is intentionally gated out on wasm32.

Architectural notes for next session

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.

8.6 KiB Raw Blame History