feat(catalog): comprehensive 2D Maps SDK capabilities catalog and visual testing

Achieve 100% Core Maps SDK for Android programmatic capability parity with official index (capabilities.json).

Key changes:
- Migrate snippets into clean kotlin-app and java-app hierarchical snippet structures
- Implement reflection-based SnippetRegistry with @snippetgroup and @SnippetItem annotations
- Add DataDrivenBoundarySnippets and DatasetLayerSnippets covering Cloud DDS capabilities
- Add CloudCustomizationSnippets demonstrating Cloud Console styling workflows loaded via Map ID
- Add StreetViewSnippets registering panorama initialization, gestures, and camera animations
- Add setMapColorScheme and enableTrafficLayer snippets to MapInitSnippets
- Add instrumented test verification suite in SnippetDiscoveryTest
- Add Gemini visual test automation framework capturing 25% scaled device screenshots
- Add automated catalog generator (test/verify_catalog.py) maintaining CATALOG.md and COVERAGE.md

Author: dkhawk

.gitignore

@@ -9,4 +9,11 @@ secrets.properties
 
 # This covers new IDEs, like Antigravity
 .vscode/
-**/bin/
+**/bin/
+
+# Temporary verification screenshot files
+*_screen*.png
+sydney_final.png
+*_sydney.png
+*_verified.png
+!**/assets/screenshots/*.png

check_api_key.gradle.kts

@@ -0,0 +1,66 @@
+import java.util.Properties
+import org.gradle.api.GradleException
+
+/**
+ * Standalone API Key & Secrets Enforcement Script
+ *
+ * Checks for a valid Google Maps API key (starts with 'AIza') before executing build tasks.
+ * Designed to be imported on-demand into application modules.
+ */
+
+val secretsFile = rootProject.file("secrets.properties")
+val isCI = System.getenv("CI")?.toBoolean() ?: false
+
+if (!isCI) {
+    val requestedTasks = gradle.startParameter.taskNames
+
+    // 1. Allow Android Studio IDE sync (empty task invocation) to complete successfully
+    if (requestedTasks.isEmpty() && !secretsFile.exists()) {
+        println("⚠️ Warning: secrets.properties not found. Gradle sync will succeed, but building/running the app will fail.")
+    } else if (requestedTasks.isNotEmpty()) {
+
+        // 2. Identify if the current invocation builds or installs the application
+        val buildTaskKeywords = listOf("build", "install", "assemble", "bundle")
+        val isBuildTask = requestedTasks.any { task ->
+            buildTaskKeywords.any { keyword -> task.contains(keyword, ignoreCase = true) }
+        }
+
+        // 3. Allow pure verification runs (unit tests, static analysis) to proceed without keys
+        val testTaskKeywords = listOf("test", "report", "lint")
+        val isTestTask = requestedTasks.any { task ->
+            testTaskKeywords.any { keyword -> task.contains(keyword, ignoreCase = true) }
+        }
+
+        if (isBuildTask && !isTestTask) {
+            val defaultsFile = rootProject.file("local.defaults.properties")
+            val requiredKeysMessage = if (defaultsFile.exists()) {
+                defaultsFile.readText()
+            } else {
+                "MAPS_API_KEY=<YOUR_API_KEY>"
+            }
+
+            if (!secretsFile.exists()) {
+                throw GradleException(
+                    "Build Blocked: 'secrets.properties' file not found.\n" +
+                    "Please create 'secrets.properties' in the root project directory with the following content:\n\n" +
+                    requiredKeysMessage
+                )
+            }
+
+            // 4. Validate key integrity via Properties and Regex checking
+            val secrets = Properties()
+            secretsFile.inputStream().use { secrets.load(it) }
+
+            // Check for relevant key names (e.g., MAPS_API_KEY or MAPS3D_API_KEY)
+            val apiKey = secrets.getProperty("MAPS_API_KEY") ?: secrets.getProperty("MAPS3D_API_KEY") ?: ""
+            println("Checking API Key in secrets.properties: '$apiKey'")
+
+            if (apiKey.isBlank() || !apiKey.matches(Regex("^AIza[a-zA-Z0-9_-]{35}$"))) {
+                throw GradleException(
+                    "Build Blocked: Invalid or missing Google Maps API key in 'secrets.properties'.\n" +
+                    "Please provide a valid API key starting with 'AIza'."
+                )
+            }
+        }
+    }
+}

gradle/libs.versions.toml

@@ -38,6 +38,7 @@ materialIconsExtended = "1.7.8"
 # Google Maps & Places
 mapsCompose = "7.0.0"
 mapsKtx = "6.0.0"
+mapsUtils = "3.19.0"
 places = "5.1.1"
 playServicesMaps = "20.0.0"
 secretsGradlePlugin = "2.0.1"
@@ -66,6 +67,8 @@ firebaseDatabase = "22.0.1"
 # Third Party
 easypermissions = "3.0.0"
 volley = "1.2.1"
+ktor = "3.4.2"
+kotlinxSerialization = "1.11.0"
 
 [libraries]
 # Kotlin
@@ -102,6 +105,7 @@ ui-tooling-preview = { module = "androidx.compose.ui:ui-tooling-preview", versio
 # Maps & Places
 maps-compose = { module = "com.google.maps.android:maps-compose", version.ref = "mapsCompose" }
 maps-ktx = { group = "com.google.maps.android", name = "maps-ktx", version.ref = "mapsKtx" }
+maps-utils = { group = "com.google.maps.android", name = "android-maps-utils", version.ref = "mapsUtils" }
 maps-utils-ktx = { group = "com.google.maps.android", name = "maps-utils-ktx", version.ref = "mapsKtx" }
 places = { group = "com.google.android.libraries.places", name = "places", version.ref = "places" }
 play-services-maps = { group = "com.google.android.gms", name = "play-services-maps", version.ref = "playServicesMaps" }
@@ -138,6 +142,11 @@ firebase-database = { module = "com.google.firebase:firebase-database", version.
 # Third Party
 easypermissions = { group = "pub.devrel", name = "easypermissions", version.ref = "easypermissions" }
 volley = { group = "com.android.volley", name = "volley", version.ref = "volley" }
+ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
+ktor-client-cio = { module = "io.ktor:ktor-client-cio", version.ref = "ktor" }
+ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
+ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerialization" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }

local.defaults.properties

@@ -3,3 +3,4 @@ BOULDER_DATASET_ID=BOULDER_DATASET_ID
 NEW_YORK_DATASET_ID=NEW_YORK_DATASET_ID
 KYOTO_DATASET_ID=KYOTO_DATASET_ID
 MAP_ID=MAP_ID
+GEMINI_API_KEY=YOUR_GEMINI_API_KEY

settings.gradle.kts

@@ -53,20 +53,23 @@ include(":WearOS:Wearable")
 project(":WearOS:Wearable").projectDir = file("WearOS/Wearable")
 
 // Snippets
-include(":snippets:app")
-project(":snippets:app").projectDir = file("snippets/app")
-include(":snippets:app-ktx")
-project(":snippets:app-ktx").projectDir = file("snippets/app-ktx")
-include(":snippets:app-utils-ktx")
-project(":snippets:app-utils-ktx").projectDir = file("snippets/app-utils-ktx")
+include(":snippets:common")
+project(":snippets:common").projectDir = file("snippets/common")
+include(":snippets:java-app")
+project(":snippets:java-app").projectDir = file("snippets/java-app")
+include(":snippets:kotlin-app")
+project(":snippets:kotlin-app").projectDir = file("snippets/kotlin-app")
 include(":snippets:app-compose")
 project(":snippets:app-compose").projectDir = file("snippets/app-compose")
 include(":snippets:app-places-ktx")
 project(":snippets:app-places-ktx").projectDir = file("snippets/app-places-ktx")
-include(":snippets:app-utils")
-project(":snippets:app-utils").projectDir = file("snippets/app-utils")
 
 // Tutorials
 include(":tutorials:kotlin:Polygons")
 project(":tutorials:kotlin:Polygons").projectDir = file("tutorials/kotlin/Polygons/app")
 // Add others as needed, starting with these for now
+
+// Visual Testing
+include(":visual-testing")
+project(":visual-testing").projectDir = file("visual-testing")
+