WIP: Overhaul sample architecture with unified Front Door, in-sample framework switching, single APK, and map reset

[dkhawk]

📌 Overview (Work in Progress)

This PR is a comprehensive architectural overhaul of the Google Maps 3D demo suite to dramatically streamline developer discovery, eliminate sample app clutter on test devices, and enable instant cross-framework comparisons.

Note

This is a Draft PR submitted for early architectural feedback and alignment on the unified showcase structure.

---

🚀 Key Improvements

1. Unified "Front Door" & Searchable Tiered Catalog

• Framework Front Door: Fast, branded entry screen for ⚛️ Jetpack Compose, 💜 Kotlin Views, and ☕ Java Views with choice persistence (SharedPreferences).
• Pedagogical Tiers: Samples categorized by difficulty:
  • 🟢 Beginner: Hello Map, Map Modes, Camera Controls, Camera Restrictions
  • 🟡 Intermediate: Markers, Polylines, Polygons, 3D Models, Popovers, Cloud Styling
  • 🔴 Advanced: Routes API, Path Following (VSYNC), Flight Simulator, Data Viz, Animating Models, FOV, Map Interactions
• Real-Time Search & Tag Filtering: Instant filtering across titles, descriptions, and tags (e.g., #camera, #vsync, #extrusion, #routes).
• Edge-to-Edge & Camera Cutout Safe: Built-in safe padding for camera punch holes, notches, status bars, and navigation bars.

2. In-Sample "Rosetta Stone" Framework Switcher

• Every sample now features an app bar cycler button ([ ⇄ 💜 Kotlin ], [ ⇄ ☕ Java ], [ ⇄ ⚛️ Compose ]).
• Developers can jump directly between Compose, Kotlin Views, and Java Views implementations of the same sample without returning to the main menu.

3. Single Unified APK Packaging

• Converted :kotlin-app and :java-app into Android library modules, aggregating all 50+ activities into a single application target.
• Users and developers only need to install one application icon on their device.

4. Map State Reset Mechanism (MapResetHelper)

• Fixes the Maps 3D SDK native engine state bleed (e.g. Map mode staying in Roadmap/Satellite, bounds clamping, lingering click listeners).
• Employs a dual-reset pattern: immediate baseline reset + delayed viewport stabilization reset (400ms) + teardown cleanup on onDestroy / onRelease.

5. Compose Lifecycle Bridge

• Added DisposableEffect with LifecycleEventObserver and onResume() in GoogleMap3D to guarantee the native GL rendering surface unpauses immediately.

---

🧪 Verification & Testing

• ✅ Clean spotless & ktlint verification (./gradlew spotlessApply).
• ✅ Unit tests passing (./gradlew testDebugUnitTest).
• ✅ Verified on physical hardware across all 3 frameworks:
  • Front Door selection & persistence.
  • In-sample cross-framework switching (Compose ➔ Kotlin Views ➔ Java Views ➔ Compose).
  • Transitioning from RoadmapMode to HelloMap cleanly resets to Hybrid mode without state bleeding.

---

CC: @LoyalAbbas