ADFA-2436: Add Maps (offline OSM) plugin

README.md

@@ -35,6 +35,7 @@ See the official [plugin documentation](https://www.appdevforall.org/codeonthego
 | [`plugins/Jetpack-Compose-Preview/`](plugins/Jetpack-Compose-Preview/) | Renders Compose preview functions on the device. |
 | [`plugins/Keystore-Generator/`](plugins/Keystore-Generator/) | Creates and manages app signing keystores on the device. |
 | [`plugins/Layout-Editor/`](plugins/Layout-Editor/) | Edits Android XML layouts by dragging views. |
+| [`plugins/Maps/`](plugins/Maps/) | Builds offline map apps from OpenStreetMap regions. |
 | [`plugins/Markdown-Previewer/`](plugins/Markdown-Previewer/) | Shows a live preview of Markdown and HTML files. |
 | [`plugins/NDK-Installer/`](plugins/NDK-Installer/) | Installs the NDK and CMake, and adds a native project template. |
 | [`plugins/Project-to-Template/`](plugins/Project-to-Template/) | Turns the open project into a reusable template. |

plugins/Maps/.gitignore

@@ -0,0 +1,29 @@
+# Gradle
+.gradle/
+build/
+gradle-app.setting
+!gradle-wrapper.jar
+.gradletasknamecache
+
+# IDE
+.idea/
+*.iml
+*.ipr
+*.iws
+.project
+.classpath
+.settings/
+.kotlin/
+
+# Local configuration
+local.properties
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Test outputs
+test-results/

plugins/Maps/README.md

@@ -0,0 +1,96 @@
+# Maps: Offline OpenStreetMap for Code on the Go
+
+`Maps` scaffolds an OpenStreetMap app in minutes. It downloads a map region and wires it into a
+MapLibre renderer, so the generated app shows a real, pannable map with no network connection —
+built for offline-first, low-bandwidth use.
+
+You start by creating a project from the **Offline OSM Map** template in the New Project wizard
+— a basic MapLibre map app. The plugin then adds a **Maps** tab to the editor bottom sheet,
+where you download a map region and bundle it into that app.
+
+## Features
+
+- **Start from a template**: create an **Offline OSM Map** project (Kotlin or Java) — a basic
+  MapLibre map app, ready to drop a region into.
+- **Download a region**: from the **Maps** tab, draw a bounding box on a world map and the
+  plugin slices out just that region's OpenStreetMap vector tiles (PMTiles) from an
+  Internet-in-a-Box source — with a live size estimate and an automatic zoom cap to keep
+  downloads small.
+- **Bundle it into your app**: apply a downloaded region to your **Offline OSM Map** project and
+  its tiles are copied into the app's assets, ready to render offline.
+- **Builds and runs offline**: the generated app renders tiles — place and street-name labels
+  included — through MapLibre and an in-process loopback HTTP server, with no network calls. It
+  even builds on-device without internet, since MapLibre is vendored.
+
+## Architecture
+
+```
+plugins/Maps/
+├── addon.json                  # Gallery metadata
+├── build.gradle.kts            # Build configuration (plugin API via ../../libs)
+├── settings.gradle.kts         # Buildscript classpath (shared ../../libs)
+├── maps.html                   # Full plugin documentation
+├── src/main/
+│   ├── AndroidManifest.xml     # Plugin metadata, permissions, icons
+│   ├── kotlin/org/appdevforall/maps/
+│   │   ├── MapsPlugin.kt       # Main plugin class (registers the tab + template)
+│   │   ├── domain/             # Pure types: bbox, zoom cap, region models
+│   │   ├── data/               # Region cache, downloader, installer, stores
+│   │   ├── slicer/             # PMTiles region slicer (Hilbert range decomposition)
+│   │   ├── templates/          # Project template + MapLibre app emitter
+│   │   ├── ui/                 # Maps tab, bbox picker, download wizard
+│   │   └── util/               # Atomic file I/O, byte-size formatting
+│   └── assets/
+│       ├── templates/region-map/      # The emitted MapLibre app (+ offline Maven repo)
+│       ├── docs/index.html            # In-IDE OSM + MapLibre tutorial
+│       ├── maps/natural-earth-*.pmtiles  # Bundled world basemap
+│       ├── fonts/                     # Noto Sans label glyphs (OFL)
+│       └── icon_day.png / icon_night.png
+└── README.md
+```
+
+### Plugin metadata (AndroidManifest.xml)
+- **plugin.id**: `org.appdevforall.maps`
+- **plugin.name**: `Maps`
+- **plugin.author**: App Dev For All
+- **plugin.main_class**: `org.appdevforall.maps.MapsPlugin`
+- **plugin.permissions**: `filesystem.read`, `filesystem.write`, `network.access`, `native.code`
+
+## Building the plugin
+
+```bash
+cd plugins/Maps
+../../gradlew assemblePlugin        # release -> build/plugin/maps.cgp
+../../gradlew assemblePluginDebug   # debug
+```
+
+### Installation
+1. Import the `.cgp` through Code on the Go's Plugin Manager.
+2. Open the **Maps** tab in the editor bottom sheet, or create a new project from the
+   **Offline OSM Map** template.
+
+## Usage
+
+1. **Create a new project** from the **Offline OSM Map** template (New Project wizard) — this
+   scaffolds a basic MapLibre map app (Kotlin or Java).
+2. Open the **Maps** tab in the editor bottom sheet and tap **Download new region**: draw a
+   bounding box, name it, and **Save**.
+3. **Apply** the downloaded region — its tiles are bundled into your app's assets.
+4. Build and run. The app renders your region offline.
+
+## Dependencies
+- `plugin-api`: Code on the Go Plugin API (`compileOnly`, shared `../../libs/plugin-api.jar`)
+- `org.maplibre.gl:android-sdk-opengl`: offline vector map rendering
+- `com.github.davidmoten:hilbert-curve`: PMTiles tile-range decomposition
+- `okhttp`, `androidx.*`, `material`, `kotlinx-coroutines`: networking and UI
+
+### Requirements
+- Android API 28+ (Android 9)
+- Minimum IDE version: 26.38 (the first release that bundles AGP 9, which the generated project needs)
+- Network once, to download a region's tiles (the generated app then runs and builds offline)
+
+## License
+
+Provided as-is for educational and development purposes. OpenStreetMap data is © OpenStreetMap
+contributors (ODbL); bundled fonts are Noto Sans (OFL). See
+`src/main/assets/THIRD_PARTY_LICENSES.txt` for full attribution.

plugins/Maps/addon.json

@@ -0,0 +1,16 @@
+{
+  "summary": "Builds offline map apps from OpenStreetMap regions.",
+  "description": "Download an OpenStreetMap region from an Internet-in-a-Box server and bundle it into an app made from the Offline OSM Map template. The app shows the map with no internet connection.",
+  "tags": [
+    "maps",
+    "openstreetmap",
+    "offline",
+    "templates"
+  ],
+  "origin": "appdevforall",
+  "license": "AGPL-3.0-or-later",
+  "author": {
+    "name": "App Dev For All",
+    "url": "https://www.appdevforall.org"
+  }
+}

plugins/Maps/build.gradle.kts

@@ -0,0 +1,175 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    id("com.android.application")
+    id("com.itsaky.androidide.plugins.build")
+    // Unit-test coverage. CoGo's root build uses JaCoCo 0.8.11 + Sonar; this
+    // plugin keeps a single-module report (`./gradlew jacocoTestReport`) so the
+    // covered-logic claim in the PR is reproducible. The UI layer is intentionally
+    // 0% here — fragments + MapLibre GL are device-tested via android-qa, not JVM.
+    jacoco
+}
+
+jacoco {
+    toolVersion = "0.8.11"
+}
+
+pluginBuilder {
+    pluginName = "maps"
+}
+
+android {
+    namespace = "org.appdevforall.maps"
+    compileSdk = 36
+
+    defaultConfig {
+        applicationId = "org.appdevforall.maps"
+        minSdk = 28
+        targetSdk = 36
+        versionCode = 1
+        versionName = "1.0.0"
+
+        // Code on the Go ships for these two ABIs only; MapLibre's x86 and x86_64 libraries
+        // would add about 21 MB that no host can load.
+        ndk {
+            abiFilters += listOf("arm64-v8a", "armeabi-v7a")
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    packaging {
+        resources {
+            excludes += setOf(
+                "META-INF/versions/9/OSGI-INF/MANIFEST.MF",
+                "META-INF/DEPENDENCIES",
+                "META-INF/LICENSE",
+                "META-INF/LICENSE.txt",
+                "META-INF/NOTICE",
+                "META-INF/NOTICE.txt"
+            )
+        }
+        jniLibs.useLegacyPackaging = true
+    }
+
+    androidResources {
+        noCompress.add("pmtiles")
+    }
+
+    testOptions {
+        unitTests {
+            // Production code logs via android.util.Log; in plain JVM unit tests
+            // android.util.Log is the stubbed android.jar and throws "not mocked".
+            // Returning default values makes Log calls no-ops so the pure parsing
+            // logic stays unit-testable.
+            isReturnDefaultValues = true
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // plugin-api jar is the canonical plugin contract; IDE provides at runtime.
+    compileOnly(files("../../libs/plugin-api.jar"))
+
+    implementation("androidx.appcompat:appcompat:1.6.1")
+    implementation("com.google.android.material:material:1.10.0")
+    implementation("androidx.fragment:fragment-ktx:1.8.8")
+    implementation("androidx.fragment:fragment:1.8.8")
+    implementation("androidx.recyclerview:recyclerview:1.3.2")
+    implementation("org.jetbrains.kotlin:kotlin-stdlib:2.3.21")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")
+
+    // MapLibre OpenGL ES — Vulkan unreliable on API 26-29 target audience.
+    // 13.x fixes PMTiles file-source range-header handling vs 11.x.
+    implementation("org.maplibre.gl:android-sdk-opengl:13.1.0")
+
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+
+    // Hilbert-curve range decomposition for bbox→tile-id slicing.
+    implementation("com.github.davidmoten:hilbert-curve:0.2.3")
+
+    testImplementation("junit:junit:4.13.2")
+    testImplementation("org.json:json:20210307")
+    // Local HTTP stub for unit-testing the range-fetch + download paths
+    // (HttpRangeFetcher, RegionDownloader) without hitting a real server.
+    testImplementation("com.squareup.okhttp3:mockwebserver:4.12.0")
+    // plugin-api is compileOnly for the main set (host-provided at runtime). Unit
+    // tests run on a plain JVM with no host, so they need it on the test classpath
+    // to compile + run the host-facing classes (MapsPlugin) and the test fakes.
+    testImplementation(files("../../libs/plugin-api.jar"))
+}
+
+tasks.wrapper {
+    gradleVersion = "9.6.1"
+    distributionType = Wrapper.DistributionType.BIN
+}
+
+// Disable AAR metadata checks that fail under the plugin-builder
+// pipeline (Beepy and Forms use the same workaround).
+tasks.matching {
+    it.name.contains("checkDebugAarMetadata") ||
+    it.name.contains("checkReleaseAarMetadata")
+}.configureEach {
+    enabled = false
+}
+
+tasks.withType<Test>().configureEach {
+    // Template tests read these files by path, so declare them or a template edit stays UP-TO-DATE.
+    inputs.dir("src/main/assets/templates").withPropertyName("templates")
+    System.getProperty("runOnlineSlicerTests")?.let {
+        systemProperty("runOnlineSlicerTests", it)
+    }
+    testLogging {
+        events("standardOut")
+        showStandardStreams = true
+    }
+    // Match CoGo's JaCoCo agent config so coverage data is written.
+    extensions.configure<JacocoTaskExtension> {
+        isIncludeNoLocationClasses = true
+        excludes = listOf("jdk.internal.*")
+    }
+}
+
+// Single-module unit-test coverage report. Run: `./gradlew jacocoTestReport`
+// (HTML at build/reports/jacoco/jacocoTestReport/html/index.html). UI classes
+// register 0% — they're device-tested via android-qa, not JVM-unit-testable.
+tasks.register<JacocoReport>("jacocoTestReport") {
+    dependsOn("testDebugUnitTest")
+    val fileFilter = listOf(
+        "**/R.class", "**/R\$*.class", "**/BuildConfig.*",
+        "**/Manifest*.*", "**/*Test*.*", "**/databinding/**",
+    )
+    // AGP 9 compiles Kotlin itself and writes the classes here, not to tmp/kotlin-classes.
+    val classes = fileTree(
+        layout.buildDirectory.dir("intermediates/built_in_kotlinc/debug/compileDebugKotlin/classes")
+    ) { exclude(fileFilter) }
+    classDirectories.setFrom(classes)
+    // A wrong class path yields an empty report that still passes, so fail instead.
+    doFirst {
+        check(!classes.isEmpty) { "jacocoTestReport: no main classes under ${classes.dir}" }
+    }
+    sourceDirectories.setFrom(files("src/main/kotlin"))
+    // Scope execution data to the exact exec file (not a build-dir-wide scan) so
+    // Gradle doesn't see this task as implicitly consuming other tasks' outputs.
+    executionData.setFrom(layout.buildDirectory.file("jacoco/testDebugUnitTest.exec"))
+    reports {
+        xml.required.set(true)
+        html.required.set(true)
+    }
+}

plugins/Maps/gradle.properties

@@ -0,0 +1,10 @@
+# Android properties
+android.useAndroidX=true
+
+# Kotlin
+kotlin.code.style=official
+
+# Memory settings for builds
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+org.gradle.parallel=true
+org.gradle.caching=true