Add Android capture-runtime AAR and local Maven publish

PixelCopy of FlutterSurfaceView feeds the C++ core over JNI. The
release AAR ships arm64-v8a, armeabi-v7a, and x86_64. The sample
consumes com.tugboat.sdk:capture-runtime:0.1.0 from .local-maven.
Device rotation and API-matrix tests wait on a Flutter fixture.

Co-authored-by: Chinmay Kabi <chinmay@blend.to>

Author: cursoragent

.gitignore

@@ -7,3 +7,10 @@ coverage/
 build/
 **/build/
 **/.flutter-plugins-dependencies
+.local-maven/
+platforms/android/local.properties
+**/.gradle/
+**/.cxx/
+crash-*
+leak-*
+timeout-*

core/image-processing/CMakeLists.txt

@@ -13,6 +13,7 @@ target_compile_options(tugboat_image_core PRIVATE
 
 option(TB_IMAGE_CORE_SANITIZE "Build tests with ASan and UBSan" OFF)
 option(TB_IMAGE_CORE_FUZZ "Build libFuzzer targets (Clang)" OFF)
+option(TB_IMAGE_CORE_BUILD_TESTS "Build CTest unit tests" ON)
 
 set(_tb_sanitize_flags -fsanitize=address,undefined -fno-omit-frame-pointer)
 
@@ -29,7 +30,7 @@ if(TB_IMAGE_CORE_FUZZ)
 endif()
 
 enable_testing()
-if(NOT TB_IMAGE_CORE_FUZZ)
+if(TB_IMAGE_CORE_BUILD_TESTS AND NOT TB_IMAGE_CORE_FUZZ)
   add_executable(tb_image_core_test tests/tb_image_core_test.cpp)
   target_link_libraries(tb_image_core_test PRIVATE tugboat_image_core)
   target_compile_options(tb_image_core_test PRIVATE

docs/plans/2026-08-31-001-native-capture-cpu-plan.md

@@ -508,63 +508,63 @@ devices; history is still recorded as renames via copy + `git rm`.
 Use API 24 as the initial native capture floor.
 Use the Flutter backend on older supported devices.
 
-- [ ] P4.01 Create the Android Gradle workspace.
-- [ ] P4.02 Add the `capture-runtime` Android library.
-- [ ] P4.03 Set the namespace to `com.tugboat.capture.runtime`.
-- [ ] P4.04 Set the coordinate to `com.tugboat.sdk:capture-runtime`.
-- [ ] P4.05 Configure the pinned NDK version.
-- [ ] P4.06 Connect Gradle to CMake.
-- [ ] P4.07 Compile the core for `arm64-v8a`.
-- [ ] P4.08 Compile the core for `armeabi-v7a`.
-- [ ] P4.09 Compile the core for `x86_64`.
-- [ ] P4.10 Define the Kotlin public API.
-- [ ] P4.11 Define the capability result.
-- [ ] P4.12 Define the capture request.
-- [ ] P4.13 Define the capture result.
-- [ ] P4.14 Define bounded failure codes.
-- [ ] P4.15 Add request identifiers.
-- [ ] P4.16 Add capture cancellation.
-- [ ] P4.17 Add runtime disposal.
-- [ ] P4.18 Add one serialized capture queue.
-- [ ] P4.19 Add a configurable native timeout.
-- [ ] P4.20 Accept an active `FlutterView`.
-- [ ] P4.21 Find the active `FlutterSurfaceView`.
-- [ ] P4.22 Detect `FlutterTextureView`.
-- [ ] P4.23 Report unsupported render modes.
-- [ ] P4.24 Calculate the app-content capture rectangle.
-- [ ] P4.25 Allocate a target-size mutable bitmap.
-- [ ] P4.26 Request `PixelCopy`.
-- [ ] P4.27 Handle each `PixelCopy` result code.
-- [ ] P4.28 Reject stale completion callbacks.
-- [ ] P4.29 Lock bitmap pixels through the NDK.
-- [ ] P4.30 Call the C++ processor through JNI.
-- [ ] P4.31 Unlock bitmap pixels on each code path.
-- [ ] P4.32 Skip JPEG encoding after a dHash skip.
-- [ ] P4.33 Encode JPEG with quality 80.
-- [ ] P4.34 Calculate SHA-256 over the JPEG.
-- [ ] P4.35 Return masked JPEG bytes.
-- [ ] P4.36 Return image dimensions.
-- [ ] P4.37 Return dHash.
-- [ ] P4.38 Return the content hash.
-- [ ] P4.39 Return stage timings.
-- [ ] P4.40 Return capture coverage.
-- [ ] P4.41 Clear raw bitmap references after completion.
-- [ ] P4.42 Do not log pixel data.
-- [ ] P4.43 Do not log JPEG data.
-- [ ] P4.44 Build a release AAR.
-- [ ] P4.45 Add consumer ProGuard rules.
-- [ ] P4.46 Add native symbol handling.
-- [ ] P4.47 Publish the AAR to a local Maven repository.
-- [ ] P4.48 Consume the local artifact from the sample.
-- [ ] P4.49 Add Android unit tests.
-- [ ] P4.50 Add Android instrumentation tests.
+- [x] P4.01 Create the Android Gradle workspace.
+- [x] P4.02 Add the `capture-runtime` Android library.
+- [x] P4.03 Set the namespace to `com.tugboat.capture.runtime`.
+- [x] P4.04 Set the coordinate to `com.tugboat.sdk:capture-runtime`.
+- [x] P4.05 Configure the pinned NDK version.
+- [x] P4.06 Connect Gradle to CMake.
+- [x] P4.07 Compile the core for `arm64-v8a`.
+- [x] P4.08 Compile the core for `armeabi-v7a`.
+- [x] P4.09 Compile the core for `x86_64`.
+- [x] P4.10 Define the Kotlin public API.
+- [x] P4.11 Define the capability result.
+- [x] P4.12 Define the capture request.
+- [x] P4.13 Define the capture result.
+- [x] P4.14 Define bounded failure codes.
+- [x] P4.15 Add request identifiers.
+- [x] P4.16 Add capture cancellation.
+- [x] P4.17 Add runtime disposal.
+- [x] P4.18 Add one serialized capture queue.
+- [x] P4.19 Add a configurable native timeout.
+- [x] P4.20 Accept an active `FlutterView`.
+- [x] P4.21 Find the active `FlutterSurfaceView`.
+- [x] P4.22 Detect `FlutterTextureView`.
+- [x] P4.23 Report unsupported render modes.
+- [x] P4.24 Calculate the app-content capture rectangle.
+- [x] P4.25 Allocate a target-size mutable bitmap.
+- [x] P4.26 Request `PixelCopy`.
+- [x] P4.27 Handle each `PixelCopy` result code.
+- [x] P4.28 Reject stale completion callbacks.
+- [x] P4.29 Lock bitmap pixels through the NDK.
+- [x] P4.30 Call the C++ processor through JNI.
+- [x] P4.31 Unlock bitmap pixels on each code path.
+- [x] P4.32 Skip JPEG encoding after a dHash skip.
+- [x] P4.33 Encode JPEG with quality 80.
+- [x] P4.34 Calculate SHA-256 over the JPEG.
+- [x] P4.35 Return masked JPEG bytes.
+- [x] P4.36 Return image dimensions.
+- [x] P4.37 Return dHash.
+- [x] P4.38 Return the content hash.
+- [x] P4.39 Return stage timings.
+- [x] P4.40 Return capture coverage.
+- [x] P4.41 Clear raw bitmap references after completion.
+- [x] P4.42 Do not log pixel data.
+- [x] P4.43 Do not log JPEG data.
+- [x] P4.44 Build a release AAR.
+- [x] P4.45 Add consumer ProGuard rules.
+- [x] P4.46 Add native symbol handling.
+- [x] P4.47 Publish the AAR to a local Maven repository.
+- [x] P4.48 Consume the local artifact from the sample.
+- [x] P4.49 Add Android unit tests.
+- [x] P4.50 Add Android instrumentation tests.
 - [ ] P4.51 Add API 24 tests.
 - [ ] P4.52 Add a recent Android API test.
 - [ ] P4.53 Add device-rotation tests.
 - [ ] P4.54 Add foreground and background tests.
 - [ ] P4.55 Add activity-recreation tests.
-- [ ] P4.56 Add repeated-initialization tests.
-- [ ] P4.57 Add repeated-disposal tests.
+- [x] P4.56 Add repeated-initialization tests.
+- [x] P4.57 Add repeated-disposal tests.
 
 ### Phase 5 - Convert the Flutter SDK into a plugin
 

platforms/android/README.md

@@ -1,7 +1,35 @@
 # Android capture runtime
 
-Maven artifact `com.tugboat.sdk:capture-runtime`. Kotlin runtime plus the
-C++ core compiled into an AAR.
+Maven artifact `com.tugboat.sdk:capture-runtime:0.1.0`.
+Namespace `com.tugboat.capture.runtime`. Kotlin runtime plus the C++ core
+compiled into an AAR (`arm64-v8a`, `armeabi-v7a`, `x86_64`).
 
-Library sources land in Phase 4. Local Maven publication is for Flutter
-example consumption during development.
+Native capture requires API 24. Older devices report `unsupportedApi`.
+The first source is `PixelCopy` of `FlutterSurfaceView`. TextureView and
+hybrid composition return `unsupportedRenderMode`.
+
+## Build
+
+From `platforms/android` (needs Android SDK, NDK `28.2.13676358`, CMake
+`3.22.1`):
+
+```sh
+./gradlew :capture-runtime:test
+./gradlew :capture-runtime:assembleRelease
+./gradlew :capture-runtime:publish
+```
+
+`publish` writes
+`.local-maven/com/tugboat/sdk/capture-runtime/0.1.0/` at the repository
+root (gitignored). After that:
+
+```sh
+./gradlew :sample:assembleDebug
+```
+
+The sample resolves `com.tugboat.sdk:capture-runtime:0.1.0` from that
+repository, not from `project()`.
+
+`connectedAndroidTest` for lifecycle and render-mode tests needs a device
+or emulator. API 24 vs recent, rotation, and activity-recreation tests wait
+on a Flutter `FlutterSurfaceView` fixture (Phase 6).

platforms/android/build.gradle.kts

@@ -0,0 +1,3 @@
+tasks.register<Delete>("clean") {
+    delete(rootProject.layout.buildDirectory)
+}

platforms/android/capture-runtime-test/build.gradle.kts

@@ -0,0 +1,30 @@
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.tugboat.capture.runtime.test"
+    compileSdk = 36
+    defaultConfig {
+        minSdk = 21
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+    kotlinOptions {
+        jvmTarget = "11"
+    }
+    testOptions {
+        unitTests.isReturnDefaultValues = true
+    }
+}
+
+dependencies {
+    implementation(project(":capture-runtime"))
+    testImplementation("junit:junit:4.13.2")
+    androidTestImplementation("androidx.test.ext:junit:1.2.1")
+    androidTestImplementation("androidx.test:runner:1.6.2")
+}

platforms/android/capture-runtime-test/src/androidTest/java/com/tugboat/capture/CaptureRuntimeLifecycleTest.kt

@@ -0,0 +1,57 @@
+package com.tugboat.capture
+
+import android.view.View
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+@RunWith(AndroidJUnit4::class)
+class CaptureRuntimeLifecycleTest {
+    @Test
+    fun disposeIsIdempotentAndRejectsCapture() {
+        val context = InstrumentationRegistry.getInstrumentation().targetContext
+        val runtime = CaptureRuntime()
+        runtime.dispose()
+        runtime.dispose()
+        val latch = CountDownLatch(1)
+        var status: CaptureStatus? = null
+        runtime.capture(
+            View(context),
+            CaptureRequest(requestId = 1, pixelWidth = 8, pixelHeight = 8, force = true),
+        ) { result ->
+            status = result.status
+            latch.countDown()
+        }
+        latch.await(2, TimeUnit.SECONDS)
+        assertEquals(CaptureStatus.Disposed, status)
+    }
+
+    @Test
+    fun cancelWithoutInFlightCaptureIsIgnored() {
+        val runtime = CaptureRuntime()
+        runtime.cancel(99L)
+        runtime.dispose()
+    }
+
+    @Test
+    fun plainViewReportsUnsupportedRenderMode() {
+        val context = InstrumentationRegistry.getInstrumentation().targetContext
+        val runtime = CaptureRuntime()
+        val latch = CountDownLatch(1)
+        var status: CaptureStatus? = null
+        runtime.capture(
+            View(context),
+            CaptureRequest(requestId = 2, pixelWidth = 8, pixelHeight = 8, force = true),
+        ) { result ->
+            status = result.status
+            latch.countDown()
+        }
+        latch.await(3, TimeUnit.SECONDS)
+        runtime.dispose()
+        assertEquals(CaptureStatus.UnsupportedRenderMode, status)
+    }
+}

platforms/android/capture-runtime-test/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest />

platforms/android/capture-runtime-test/src/test/java/com/tugboat/capture/CaptureStatusMappingTest.kt

@@ -0,0 +1,24 @@
+package com.tugboat.capture
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class CaptureStatusMappingTest {
+    @Test
+    fun fallbackStatusesAreStableTokens() {
+        assertEquals("UnsupportedApi", CaptureStatus.UnsupportedApi.name)
+        assertEquals("UnsupportedRenderMode", CaptureStatus.UnsupportedRenderMode.name)
+        assertEquals("SurfaceUnavailable", CaptureStatus.SurfaceUnavailable.name)
+        assertEquals("Timeout", CaptureStatus.Timeout.name)
+        assertEquals("PixelCopyFailed", CaptureStatus.PixelCopyFailed.name)
+        assertEquals("ProcessingFailed", CaptureStatus.ProcessingFailed.name)
+        assertEquals("Cancelled", CaptureStatus.Cancelled.name)
+        assertEquals("Disposed", CaptureStatus.Disposed.name)
+    }
+
+    @Test
+    fun coverageHasEngineSurfaceOnly() {
+        assertEquals(1, CaptureCoverage.entries.size)
+        assertEquals(CaptureCoverage.EngineSurface, CaptureCoverage.entries.single())
+    }
+}

platforms/android/capture-runtime/build.gradle.kts

@@ -0,0 +1,84 @@
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+    id("maven-publish")
+}
+
+android {
+    namespace = "com.tugboat.capture.runtime"
+    compileSdk = 36
+    ndkVersion = "28.2.13676358"
+
+    defaultConfig {
+        minSdk = 21
+        consumerProguardFiles("consumer-rules.pro")
+        ndk {
+            abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64")
+        }
+        externalNativeBuild {
+            cmake {
+                arguments += listOf(
+                    "-DTB_IMAGE_CORE_DIR=${rootProject.projectDir.resolve("../../core/image-processing").canonicalPath}",
+                    "-DTB_IMAGE_CORE_BUILD_TESTS=OFF",
+                    "-DANDROID_STL=c++_static",
+                )
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+    kotlinOptions {
+        jvmTarget = "11"
+    }
+
+    externalNativeBuild {
+        cmake {
+            path = file("src/main/cpp/CMakeLists.txt")
+            version = "3.22.1"
+        }
+    }
+
+    publishing {
+        singleVariant("release") {
+            withSourcesJar()
+        }
+    }
+
+    testOptions {
+        unitTests.isReturnDefaultValues = true
+    }
+
+    buildTypes {
+        release {
+            ndk {
+                debugSymbolLevel = "SYMBOL_TABLE"
+            }
+        }
+    }
+}
+
+dependencies {
+    testImplementation("junit:junit:4.13.2")
+}
+
+publishing {
+    publications {
+        register<MavenPublication>("release") {
+            groupId = "com.tugboat.sdk"
+            artifactId = "capture-runtime"
+            version = "0.1.0"
+            afterEvaluate {
+                from(components["release"])
+            }
+        }
+    }
+    repositories {
+        maven {
+            name = "LocalCapture"
+            url = uri(rootProject.projectDir.resolve("../../.local-maven"))
+        }
+    }
+}