docs(handoff): record Android launch verification; update status

Closes the APK launch verification punch-list item. Three fixes in
202a64d boot the app on Pixel_7 AVD (Android 14, x86_64). Next open
arcs: Phase 8 (sync) or Android JNI follow-ups.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -6,8 +6,9 @@ project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-**`a449f60`** — Stats overlay Prev/Next replay selector spawn site
+**`202a64d`** — Android APK launch fixes (2026-05-08).
-(2026-05-08). See [0.21.9] for the committed detail once cut.
+**`16242e6`** — Ignore .idea/ IDE files (2026-05-08).
+See [0.21.9] for the committed detail once cut.
 
 ## [0.21.9] — pending cut
 
@@ -45,12 +46,41 @@ v0.19.0.
   `clippy::assertions_on_constants` (constant-fold at compile time
   rather than a runtime no-op).
 
+### Fixed (post-cut, same pending release)
+
+- **Android APK launch: export `android_main`** (`202a64d`).
+  `NativeActivity` dlopen-s `libsolitaire_app.so` and calls
+  `android_main` as its entry point. Without the symbol the app
+  crashed immediately with `UnsatisfiedLinkError`. The new function
+  sets `bevy::android::ANDROID_APP` (required by `WinitPlugin`) then
+  delegates to `run()` — equivalent to what `#[bevy_main]` would
+  generate, but usable on an arbitrary entry point name.
+- **Android APK launch: gate `resize_constraints` to non-Android**
+  (`202a64d`). On Android `max_width/max_height` default to `0.0`;
+  Bevy's clamp panicked with `min=800 > max=0`.
+- **Android APK launch: gate `apply_smart_default_window_size` to
+  non-Android** (`202a64d`). The system calls `.clamp(800.0,
+  logical_w)` which panics when the emulator reports zero window
+  dimensions during early Android lifecycle events. The OS controls
+  window size on Android; the system is irrelevant there.
+- **Ignore `.idea/` IDE project files** (`16242e6`). Android Studio
+  created `.idea/` when the project was opened during APK
+  verification; added to `.gitignore` and removed the accidentally-
+  committed files.
+
+### Android verification result
+
+APK boots on `x86_64-linux-android` in a Pixel_7 AVD (Android 14 /
+API 34, SwiftShader Vulkan). App runs for 2+ minutes without crashing.
+Bevy renderer initialises, splash screen loads. This is the first
+confirmed end-to-end device run.
+
 ### Stats
 
-- Tests: 1282 passing / 0 failing (was 1276; +6 selector tests)
+- Tests: 1282 passing / 0 failing (unchanged)
 - Clippy: clean
 - Crates touched: `solitaire_engine` (stats_plugin.rs,
-  replay_overlay.rs)
+  replay_overlay.rs), `solitaire_app` (lib.rs, .gitignore)
 
 ## [0.21.8] — 2026-05-08
 

SESSION_HANDOFF.md

@@ -1,8 +1,8 @@
 # Solitaire Quest — Session Handoff
 
 **Last updated:** 2026-05-08 — **v0.21.8 tagged at `c50eaf8`**;
-one post-cut commit `a449f60` (Stats Prev/Next selector spawn site)
+three post-cut commits on master (`a449f60` Stats selector,
-is on master, uncommitted docs ride on top, push pending.
+`202a64d` Android launch fixes, `16242e6` .gitignore). Pushed.
 
 v0.21.8 closes the last optional polish items in the B-2
 replay screen-takeover arc: **notch-label centering** (middle
@@ -19,51 +19,52 @@ resume.
 
 ## Status at pause
 
-- **HEAD locally:** `a449f60` (Stats Prev/Next selector spawn).
+- **HEAD locally:** `16242e6` (.gitignore fix). Docs ride on top;
-  Docs ride on top; push pending:
+  push pending.
-  `git push origin master && git push origin v0.21.8`.
+- **HEAD on origin:** `c0415eb` (handoff docs from prior session).
-- **HEAD on origin:** `52407e7` (v0.21.7 docs). v0.21.8 and
+  `202a64d` and `16242e6` not yet pushed.
-  v0.21.9 not yet pushed.
 - **Working tree:** clean (docs uncommitted). No WIP outstanding.
 - **`artwork/` directory:** still untracked. Intentional.
 - **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
   clean.
 - **Tests:** **1282 passing / 0 failing** across the workspace.
-  Detail in `CHANGELOG.md` § [0.21.9] § Stats.
+- **Tags on origin:** `v0.9.0` through `v0.21.8`.
-- **Tags on origin:** `v0.9.0` through `v0.21.7`. v0.21.8 tag
+- **Android:** APK verified booting on Pixel_7 AVD (Android 14,
-  exists locally at `c50eaf8`; push when pushing master.
+  x86_64). Three launch fixes committed. See Phase Android punch
+  list for remaining work.
 
 ## Since the v0.21.8 cut
 
-One commit since the v0.21.8 tag (not yet pushed):
+Three commits since the v0.21.8 tag:
-- `a449f60` — Stats Prev/Next selector spawn site (closes
+- `a449f60` — Stats Prev/Next selector spawn site
-  punch-list item "Prev/Next selector chips spawn site" from
+- `202a64d` — Android launch fixes (android_main, resize_constraints,
-  v0.19.0's `9b065e5`)
+  apply_smart_default_window_size) — **closes APK launch verification**
+- `16242e6` — Ignore .idea/ IDE files
 
-CHANGELOG + SESSION_HANDOFF docs ride on top.
+CHANGELOG + SESSION_HANDOFF docs ride on top; push pending.
 
-Open next-step menu (B-2 arc fully closed, Prev/Next selector
+Open next-step menu:
-spawn site closed; no known open UI items):
+1. **Phase 8 (sync)** — the biggest open arc. Local storage
-1. **APK launch verification on AVD / device** — see Phase
-   Android punch list in this file.
-2. **Phase 8 (sync)** — the biggest open arc. Local storage
    scaffolding, self-hosted Axum server, GPGS stub.
+2. **Android follow-ups** — JNI ClipboardManager, Android Keystore,
+   GPGS, double-tap auto-move. Launch verification closed; these
+   are the remaining Phase Android items.
 3. **Move Log auto-scroll** — only relevant if the panel
-   row count grows beyond the current 5-row fixed window;
+   row count grows beyond the current 5-row fixed window.
-   non-starter until then.
-
-Recommended order: resume with A or C from the DECISION menu
-in the resume prompt below.
 
 ## Open punch list
 
 ### Phase Android (build + persistence shipped; runtime gaps remain)
 
-- **APK launch verification on AVD / device.** `adb install` then
+- *APK launch verification — closed 2026-05-08 by `202a64d`.*
-  `adb logcat` against the `bevy_test` AVD or an x86_64 device.
+  Three fixes shipped: `android_main` export (missing NativeActivity
-  The build works and persistence is wired, but no end-to-end
+  entry point), `resize_constraints` gated to non-Android (max=0
-  device run has been logged. Shakes out runtime bugs the build +
+  panic), `apply_smart_default_window_size` gated to non-Android
-  unit tests can't catch.
+  (clamp panic on zero-dimension window event). Verified booting on
+  Pixel_7 AVD (Android 14, x86_64, SwiftShader Vulkan), 2+ min
+  runtime without crash. B0004 ECS hierarchy warnings remain
+  (non-fatal; entity parent/child component mismatch); investigate
+  if they surface gameplay bugs.
 - **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.