@dvai-bridge/android-mediapipe-core 4.0.0 → 4.0.2

package/android/build.gradle

@@ -1,134 +1,211 @@
-buildscript {
-    ext {
-        kotlinVersion = '2.3.21'
-    }
-    repositories {
-        google()
-        mavenCentral()
-    }
-    dependencies {
-        classpath 'com.android.tools.build:gradle:9.2.0'
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
-    }
-}
-
-ext {
-    junitVersion = '4.13.2'
-    androidxAppCompatVersion = '1.7.1'
-    coroutinesVersion = '1.10.2'
-    // Pinned within Ktor 2.x — Ktor 3 has breaking API changes around server
-    // configuration that would require non-trivial refactors. Stay on the
-    // latest 2.x patch (2.3.13) until a deliberate Ktor 3 migration.
-    ktorVersion = '2.3.13'
-    // LiteRT-LM — replaces the deprecated `com.google.mediapipe:tasks-genai`
-    // (Phase 3B, Tasks 18-19). `litertlm-android` bundles the full runtime;
-    // no separate `tasks-core` companion is required.
-    // Hosted on Google Maven (google() repo, already declared in allprojects).
-    litertLmVersion = '0.10.2'
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-        // Phase 3D: shared-core lives here in dev (after `publishToMavenLocal`).
-        // Production publishes resolve from GitHub Packages.
-        mavenLocal()
-    }
-}
-
-// AGP 9+ ships built-in Kotlin support; the standalone 'kotlin-android'
-// plugin is no longer needed (and is rejected by the build).
-// See https://kotl.in/gradle/agp-built-in-kotlin
-apply plugin: 'com.android.library'
-apply plugin: 'maven-publish'
-
-android {
-    namespace 'co.deepvoiceai.bridge.mediapipe.core'
-    // Phase 2 Task 3 (examples) library fix: see shared-core/android/build.gradle
-    // for the rationale — `-PcompileSdkOverride=35` lets Windows hosts sidestep
-    // an AGP 9.2.0 parseLocalResources bug against android-36's public-final.xml.
-    compileSdk(project.findProperty('compileSdkOverride')?.toInteger() ?: 36)
-
-    defaultConfig {
-        minSdk 24
-        targetSdk(project.findProperty('compileSdkOverride')?.toInteger() ?: 36)
-        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
-    }
-
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_17
-        targetCompatibility JavaVersion.VERSION_17
-    }
-    testOptions {
-        unitTests.includeAndroidResources = true
-    }
-
-    publishing {
-        singleVariant('release') {
-            withSourcesJar()
-        }
-    }
-}
-
-// AGP 9 / Kotlin 2.x: the legacy android.kotlinOptions block is gone. The
-// replacement is the standalone `kotlin { compilerOptions { ... } }` extension
-// (provided by AGP's built-in Kotlin integration).
-kotlin {
-    compilerOptions {
-        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
-    }
-}
-
-dependencies {
-    // Phase 3D: shared HTTP server + handler dispatch types live here.
-    // `api` (not `implementation`) so consumer projects see them transitively.
-    api "co.deepvoiceai:android-shared-core:$dvaiBridgeVersion"
-
-    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
-    implementation "io.ktor:ktor-server-core:$ktorVersion"
-    implementation "io.ktor:ktor-server-cio:$ktorVersion"
-    implementation "io.ktor:ktor-server-cors:$ktorVersion"
-    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutinesVersion"
-    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0'
-    implementation 'com.squareup.okhttp3:okhttp:5.3.2'
-
-    // LiteRT-LM: non-deprecated successor to tasks-genai (Phase 3B Task 18-19).
-    // Bundles the full LLM runtime including vision support via EngineConfig.visionBackend.
-    // ~100MB native libs per ABI — first build will be slow.
-    implementation "com.google.ai.edge.litertlm:litertlm-android:$litertLmVersion"
-
-    testImplementation "junit:junit:$junitVersion"
-    testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:$coroutinesVersion"
-    testImplementation 'org.robolectric:robolectric:4.16.1'
-    testImplementation "io.ktor:ktor-server-test-host:$ktorVersion"
-    testImplementation 'com.squareup.okhttp3:mockwebserver:5.3.2'
-
-    androidTestImplementation 'androidx.test:runner:1.7.0'
-    androidTestImplementation 'androidx.test.ext:junit:1.3.0'
-}
-
-// Phase 3D Task 4: copy-paste publishing block (see llama-core for the
-// rationale on why each Gradle root has its own copy).
-afterEvaluate {
-    publishing {
-        publications {
-            release(MavenPublication) {
-                groupId = 'co.deepvoiceai'
-                artifactId = 'android-mediapipe-core'
-                version = (project.findProperty('dvaiBridgeVersion') ?: '4.0.0').toString()
-                from components.release
-            }
-        }
-        repositories {
-            maven {
-                name = 'GitHubPackages'
-                url = uri('https://maven.pkg.github.com/dvai-global/dvai-bridge')
-                credentials {
-                    username = project.findProperty('gpr.user') ?: System.getenv('GITHUB_ACTOR')
-                    password = project.findProperty('gpr.key') ?: System.getenv('GITHUB_TOKEN')
-                }
-            }
-        }
-    }
-}
+buildscript {
+    ext {
+        kotlinVersion = '2.3.21'
+    }
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:9.2.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
+        // Maven Central publishing — wraps maven-publish + signing + the
+        // Central Portal upload API into one config block. See the
+        // mavenPublishing { ... } block below.
+        classpath 'com.vanniktech:gradle-maven-publish-plugin:0.36.0'
+    }
+}
+
+ext {
+    junitVersion = '4.13.2'
+    androidxAppCompatVersion = '1.7.1'
+    coroutinesVersion = '1.10.2'
+    // Pinned within Ktor 2.x — Ktor 3 has breaking API changes around server
+    // configuration that would require non-trivial refactors. Stay on the
+    // latest 2.x patch (2.3.13) until a deliberate Ktor 3 migration.
+    ktorVersion = '2.3.13'
+    // LiteRT-LM — replaces the deprecated `com.google.mediapipe:tasks-genai`
+    // (Phase 3B, Tasks 18-19). `litertlm-android` bundles the full runtime;
+    // no separate `tasks-core` companion is required.
+    // Hosted on Google Maven (google() repo, already declared in allprojects).
+    litertLmVersion = '0.10.2'
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+        // Phase 3D: shared-core lives here in dev (after `publishToMavenLocal`).
+        // Production publishes resolve from GitHub Packages.
+        mavenLocal()
+    }
+}
+
+// AGP 9+ ships built-in Kotlin support; the standalone 'kotlin-android'
+// plugin is no longer needed (and is rejected by the build).
+// See https://kotl.in/gradle/agp-built-in-kotlin
+apply plugin: 'com.android.library'
+apply plugin: 'com.vanniktech.maven.publish'
+
+android {
+    namespace 'co.deepvoiceai.bridge.mediapipe.core'
+    // Phase 2 Task 3 (examples) library fix: see shared-core/android/build.gradle
+    // for the rationale — `-PcompileSdkOverride=35` lets Windows hosts sidestep
+    // an AGP 9.2.0 parseLocalResources bug against android-36's public-final.xml.
+    compileSdk(project.findProperty('compileSdkOverride')?.toInteger() ?: 36)
+
+    defaultConfig {
+        minSdk 24
+        targetSdk(project.findProperty('compileSdkOverride')?.toInteger() ?: 36)
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    testOptions {
+        unitTests.includeAndroidResources = true
+    }
+
+    // NB: don't add `publishing { singleVariant('release') { withSourcesJar() } }`
+    // here. The vanniktech.maven.publish plugin auto-configures Android
+    // single-variant publication + sources + javadoc jars on its own; a
+    // manual singleVariant block collides with "Using singleVariant publishing
+    // DSL multiple times to publish variant 'release' to component 'release'
+    // is not allowed."
+}
+
+// AGP 9 / Kotlin 2.x: the legacy android.kotlinOptions block is gone. The
+// replacement is the standalone `kotlin { compilerOptions { ... } }` extension
+// (provided by AGP's built-in Kotlin integration).
+kotlin {
+    compilerOptions {
+        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+    }
+}
+
+dependencies {
+    // Phase 3D: shared HTTP server + handler dispatch types live here.
+    // `api` (not `implementation`) so consumer projects see them transitively.
+    api "co.deepvoiceai:android-shared-core:$dvaiBridgeVersion"
+
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "io.ktor:ktor-server-core:$ktorVersion"
+    implementation "io.ktor:ktor-server-cio:$ktorVersion"
+    implementation "io.ktor:ktor-server-cors:$ktorVersion"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutinesVersion"
+    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0'
+    implementation 'com.squareup.okhttp3:okhttp:5.3.2'
+
+    // LiteRT-LM: non-deprecated successor to tasks-genai (Phase 3B Task 18-19).
+    // Bundles the full LLM runtime including vision support via EngineConfig.visionBackend.
+    // ~100MB native libs per ABI — first build will be slow.
+    implementation "com.google.ai.edge.litertlm:litertlm-android:$litertLmVersion"
+
+    testImplementation "junit:junit:$junitVersion"
+    testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:$coroutinesVersion"
+    testImplementation 'org.robolectric:robolectric:4.16.1'
+    testImplementation "io.ktor:ktor-server-test-host:$ktorVersion"
+    testImplementation 'com.squareup.okhttp3:mockwebserver:5.3.2'
+
+    androidTestImplementation 'androidx.test:runner:1.7.0'
+    androidTestImplementation 'androidx.test.ext:junit:1.3.0'
+}
+
+// Maven Central publishing via Sonatype Central Portal. See the
+// PUBLISHING-MAVEN-CENTRAL.md note at the repo root (gitignored — your
+// operator playbook) for credentials + the per-release sequence.
+//
+// Coordinates and POM metadata live here; the actual publish is driven
+// by `./gradlew publishAndReleaseToMavenCentral` (auto-release on
+// validation passing) or `publishToMavenLocal` for a dry-run that
+// writes the artifacts + signatures to ~/.m2/repository/.
+mavenPublishing {
+    // AGP 9.2.0 bundles a Dokka build whose ASM can't read Kotlin 2.3.21's
+    // sealed-class bytecode (`PermittedSubclasses requires ASM9`) when it
+    // tries to resolve the api jar of android-shared-core during the
+    // `javaDocReleaseGeneration` task. We bypass AGP's Dokka javadoc and
+    // ship an empty javadoc.jar instead — Sonatype Central Portal validates
+    // the artifact's presence, not that it is populated. Re-enable once
+    // AGP upgrades its bundled ASM.
+    configure(new com.vanniktech.maven.publish.AndroidSingleVariantLibrary(
+        /* variant         = */ 'release',
+        /* sourcesJar      = */ true,
+        /* publishJavadoc  = */ false,
+    ))
+
+    publishToMavenCentral(true)
+    // Sign only when the PGP key is configured — see shared-core for rationale.
+    if (project.findProperty('signingInMemoryKey') ||
+            System.getenv('ORG_GRADLE_PROJECT_signingInMemoryKey')) {
+        signAllPublications()
+    }
+
+    coordinates(
+        'co.deepvoiceai',
+        'android-mediapipe-core',
+        (project.findProperty('dvaiBridgeVersion') ?: '4.0.2').toString(),
+    )
+
+    pom {
+        name = 'DVAI Bridge Android — MediaPipe / LiteRT-LM core'
+        description = 'LiteRT-LM (Google AI Edge) backend for DVAI Bridge on Android. ' +
+                'Replaces the deprecated MediaPipe tasks-genai runtime; bundles vision ' +
+                'support via EngineConfig.visionBackend. Depends on android-shared-core ' +
+                'for the HTTP/handler layer.'
+        inceptionYear = '2026'
+        url = 'https://github.com/dvai-global/dvai-bridge'
+
+        licenses {
+            license {
+                name = 'DVAI Bridge Community Licence v1.0'
+                url = 'https://bridge.deepvoiceai.co/licensing'
+                distribution = 'repo'
+            }
+        }
+        developers {
+            developer {
+                id = 'deepvoiceai'
+                name = 'Deep Voice AI Limited'
+                email = 'info@deepvoiceai.co'
+                organization = 'Deep Voice AI Limited'
+                organizationUrl = 'https://deepvoiceai.co'
+            }
+        }
+        scm {
+            url = 'https://github.com/dvai-global/dvai-bridge'
+            connection = 'scm:git:git://github.com/dvai-global/dvai-bridge.git'
+            developerConnection = 'scm:git:ssh://github.com:dvai-global/dvai-bridge.git'
+        }
+    }
+}
+
+// Switch Gradle signing from BouncyCastle-based in-memory mode to
+// shell-out-to-gpg mode. The in-memory path can't parse GnuPG 2.4+
+// keys that carry pref-aead-algos (subpkt 34) in their user-ID
+// self-signature — `gpg --list-packets` of our v4.0.1 signing key
+// confirms that subpacket is present. useGpgCmd() shells out to the
+// local gpg binary (imported into the runner's keyring by the
+// publish.yml workflow), which can parse it. Passphrase is supplied
+// via ~/.gradle/gradle.properties (signing.gnupg.passphrase).
+if (project.findProperty('signing.gnupg.keyName') ||
+        System.getenv('ORG_GRADLE_PROJECT_USE_GPG_CMD_SIGNING') == 'true') {
+    signing {
+        useGpgCmd()
+    }
+}
+
+// Empty javadoc.jar to satisfy Sonatype Central Portal validation while
+// AGP 9.2.0's bundled Dokka is incompatible with our sealed-class bytecode.
+// See the `configure(AndroidSingleVariantLibrary ...)` comment above.
+tasks.register('emptyJavadocJar', Jar) {
+    archiveClassifier.set('javadoc')
+}
+
+afterEvaluate {
+    publishing.publications.withType(MavenPublication).configureEach { pub ->
+        pub.artifact(tasks.named('emptyJavadocJar'))
+    }
+}

package/android/gradle.properties

@@ -2,4 +2,4 @@ android.useAndroidX=true
 kotlin.code.style=official
 android.nonTransitiveRClass=true
 org.gradle.jvmargs=-Xmx4096m
-dvaiBridgeVersion=4.0.0
+dvaiBridgeVersion=4.0.2

package/android/settings.gradle

@@ -1 +1 @@
-rootProject.name = 'dvai-bridge-android-mediapipe-core'
+rootProject.name = 'dvai-bridge-android-mediapipe-core'

package/android/src/main/AndroidManifest.xml

@@ -1,14 +1,14 @@
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <application>
-        <!-- LiteRT-LM GPU backend optional native libs (Phase 3B Task 18-19).
-             android:required="false" lets devices without these still run on
-             the CPU backend rather than failing installation outright. -->
-        <uses-native-library
-            android:name="libvndksupport.so"
-            android:required="false" />
-        <uses-native-library
-            android:name="libOpenCL.so"
-            android:required="false" />
-    </application>
-</manifest>
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application>
+        <!-- LiteRT-LM GPU backend optional native libs (Phase 3B Task 18-19).
+             android:required="false" lets devices without these still run on
+             the CPU backend rather than failing installation outright. -->
+        <uses-native-library
+            android:name="libvndksupport.so"
+            android:required="false" />
+        <uses-native-library
+            android:name="libOpenCL.so"
+            android:required="false" />
+    </application>
+</manifest>

package/android/src/main/java/co/deepvoiceai/bridge/mediapipe/core/ImageDecoder.kt

@@ -1,115 +1,115 @@
-package co.deepvoiceai.bridge.mediapipe.core
-
-import okhttp3.OkHttpClient
-import okhttp3.Request
-import java.io.File
-import java.net.URI
-import java.net.URLDecoder
-import java.util.Base64
-import java.util.concurrent.TimeUnit
-
-/**
- * Errors thrown by [ImageDecoder.resolve] when the input URL string can't
- * be turned into image bytes.
- */
-sealed class ImageSourceError(msg: String) : Exception(msg) {
-    class MalformedDataURL(url: String) : ImageSourceError("malformed data URL: $url")
-    class MalformedURL(url: String) : ImageSourceError("malformed URL: $url")
-    class InvalidScheme(scheme: String) : ImageSourceError("unsupported URL scheme: $scheme")
-    class HttpError(val status: Int) : ImageSourceError("HTTP $status")
-    class Base64DecodeFailed : ImageSourceError("base64 decode failed")
-}
-
-/**
- * Resolves any of the three image URL schemes accepted by the DVAI bridge
- * (`data:`, `https:`/`http:`, `file:`) into the raw encoded image bytes
- * (PNG/JPEG/etc.). Format decoding into pixel buffers is performed downstream
- * by Android's `BitmapFactory` (then wrapped in `MPImage` via
- * `BitmapImageBuilder`) — this layer just materializes the encoded bytes.
- *
- * Byte-identical to capacitor-llama's `ImageDecoder` modulo package
- * declaration. If you fix a bug here, mirror it there (and vice versa).
- *
- * Blocking: HTTP fetches use OkHttp synchronously. Call from a background
- * thread or coroutine on `Dispatchers.IO` (the plugin layer already does).
- */
-object ImageDecoder {
-    private val httpClient: OkHttpClient by lazy {
-        // `callTimeout` caps the entire HTTP exchange (DNS + connect + write
-        // + read + redirect) at 30s so worst-case latency matches iOS, where
-        // `URLRequest.timeoutInterval = 30` covers the whole request.
-        OkHttpClient.Builder()
-            .callTimeout(30, TimeUnit.SECONDS)
-            .build()
-    }
-
-    /**
-     * Resolve any supported URL scheme into raw image bytes.
-     *
-     * - `data:` URLs are parsed for an optional `;base64` token and decoded
-     *   accordingly (URL-encoded payloads are also supported).
-     * - `https:` / `http:` URLs are fetched via OkHttp with a 30s timeout;
-     *   non-2xx responses throw [ImageSourceError.HttpError].
-     * - `file:` URLs are read off disk via [File.readBytes].
-     * - Any other scheme throws [ImageSourceError.InvalidScheme].
-     * - URLs that fail to parse, lack a scheme, or have a missing/empty
-     *   `file:` path throw [ImageSourceError.MalformedURL].
-     */
-    fun resolve(url: String): ByteArray {
-        if (url.startsWith("data:")) {
-            return resolveDataURL(url)
-        }
-        return resolveWithClient(url, httpClient)
-    }
-
-    /**
-     * Test seam: same contract as [resolve] but lets the caller inject an
-     * [OkHttpClient] (e.g. one pointed at MockWebServer). Data URLs still
-     * short-circuit before the client is consulted.
-     */
-    internal fun resolveWithClient(url: String, client: OkHttpClient): ByteArray {
-        if (url.startsWith("data:")) {
-            return resolveDataURL(url)
-        }
-        val parsed = try {
-            URI(url)
-        } catch (_: Exception) {
-            throw ImageSourceError.MalformedURL(url)
-        }
-        val scheme = parsed.scheme?.lowercase() ?: throw ImageSourceError.MalformedURL(url)
-        return when (scheme) {
-            "https", "http" -> fetchHttp(url, client)
-            "file" -> {
-                val path = parsed.path
-                if (path.isNullOrEmpty()) throw ImageSourceError.MalformedURL(url)
-                File(path).readBytes()
-            }
-            else -> throw ImageSourceError.InvalidScheme(scheme)
-        }
-    }
-
-    /** Parse a `data:[<mediatype>][;base64],<payload>` URL into raw bytes. */
-    private fun resolveDataURL(url: String): ByteArray {
-        val commaIdx = url.indexOf(',')
-        if (commaIdx < 0) throw ImageSourceError.MalformedDataURL(url)
-        // Skip the leading "data:" (5 chars) and isolate header / body.
-        val header = url.substring(5, commaIdx)
-        val body = url.substring(commaIdx + 1)
-        if (header.contains(";base64")) {
-            return try {
-                Base64.getDecoder().decode(body)
-            } catch (_: IllegalArgumentException) {
-                throw ImageSourceError.Base64DecodeFailed()
-            }
-        }
-        // Non-base64: payload is percent-encoded text per RFC 2397.
-        return URLDecoder.decode(body, Charsets.UTF_8.name()).toByteArray(Charsets.UTF_8)
-    }
-
-    private fun fetchHttp(url: String, client: OkHttpClient): ByteArray {
-        client.newCall(Request.Builder().url(url).build()).execute().use { resp ->
-            if (!resp.isSuccessful) throw ImageSourceError.HttpError(resp.code)
-            return resp.body?.bytes() ?: ByteArray(0)
-        }
-    }
-}
+package co.deepvoiceai.bridge.mediapipe.core
+
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import java.io.File
+import java.net.URI
+import java.net.URLDecoder
+import java.util.Base64
+import java.util.concurrent.TimeUnit
+
+/**
+ * Errors thrown by [ImageDecoder.resolve] when the input URL string can't
+ * be turned into image bytes.
+ */
+sealed class ImageSourceError(msg: String) : Exception(msg) {
+    class MalformedDataURL(url: String) : ImageSourceError("malformed data URL: $url")
+    class MalformedURL(url: String) : ImageSourceError("malformed URL: $url")
+    class InvalidScheme(scheme: String) : ImageSourceError("unsupported URL scheme: $scheme")
+    class HttpError(val status: Int) : ImageSourceError("HTTP $status")
+    class Base64DecodeFailed : ImageSourceError("base64 decode failed")
+}
+
+/**
+ * Resolves any of the three image URL schemes accepted by the DVAI bridge
+ * (`data:`, `https:`/`http:`, `file:`) into the raw encoded image bytes
+ * (PNG/JPEG/etc.). Format decoding into pixel buffers is performed downstream
+ * by Android's `BitmapFactory` (then wrapped in `MPImage` via
+ * `BitmapImageBuilder`) — this layer just materializes the encoded bytes.
+ *
+ * Byte-identical to capacitor-llama's `ImageDecoder` modulo package
+ * declaration. If you fix a bug here, mirror it there (and vice versa).
+ *
+ * Blocking: HTTP fetches use OkHttp synchronously. Call from a background
+ * thread or coroutine on `Dispatchers.IO` (the plugin layer already does).
+ */
+object ImageDecoder {
+    private val httpClient: OkHttpClient by lazy {
+        // `callTimeout` caps the entire HTTP exchange (DNS + connect + write
+        // + read + redirect) at 30s so worst-case latency matches iOS, where
+        // `URLRequest.timeoutInterval = 30` covers the whole request.
+        OkHttpClient.Builder()
+            .callTimeout(30, TimeUnit.SECONDS)
+            .build()
+    }
+
+    /**
+     * Resolve any supported URL scheme into raw image bytes.
+     *
+     * - `data:` URLs are parsed for an optional `;base64` token and decoded
+     *   accordingly (URL-encoded payloads are also supported).
+     * - `https:` / `http:` URLs are fetched via OkHttp with a 30s timeout;
+     *   non-2xx responses throw [ImageSourceError.HttpError].
+     * - `file:` URLs are read off disk via [File.readBytes].
+     * - Any other scheme throws [ImageSourceError.InvalidScheme].
+     * - URLs that fail to parse, lack a scheme, or have a missing/empty
+     *   `file:` path throw [ImageSourceError.MalformedURL].
+     */
+    fun resolve(url: String): ByteArray {
+        if (url.startsWith("data:")) {
+            return resolveDataURL(url)
+        }
+        return resolveWithClient(url, httpClient)
+    }
+
+    /**
+     * Test seam: same contract as [resolve] but lets the caller inject an
+     * [OkHttpClient] (e.g. one pointed at MockWebServer). Data URLs still
+     * short-circuit before the client is consulted.
+     */
+    internal fun resolveWithClient(url: String, client: OkHttpClient): ByteArray {
+        if (url.startsWith("data:")) {
+            return resolveDataURL(url)
+        }
+        val parsed = try {
+            URI(url)
+        } catch (_: Exception) {
+            throw ImageSourceError.MalformedURL(url)
+        }
+        val scheme = parsed.scheme?.lowercase() ?: throw ImageSourceError.MalformedURL(url)
+        return when (scheme) {
+            "https", "http" -> fetchHttp(url, client)
+            "file" -> {
+                val path = parsed.path
+                if (path.isNullOrEmpty()) throw ImageSourceError.MalformedURL(url)
+                File(path).readBytes()
+            }
+            else -> throw ImageSourceError.InvalidScheme(scheme)
+        }
+    }
+
+    /** Parse a `data:[<mediatype>][;base64],<payload>` URL into raw bytes. */
+    private fun resolveDataURL(url: String): ByteArray {
+        val commaIdx = url.indexOf(',')
+        if (commaIdx < 0) throw ImageSourceError.MalformedDataURL(url)
+        // Skip the leading "data:" (5 chars) and isolate header / body.
+        val header = url.substring(5, commaIdx)
+        val body = url.substring(commaIdx + 1)
+        if (header.contains(";base64")) {
+            return try {
+                Base64.getDecoder().decode(body)
+            } catch (_: IllegalArgumentException) {
+                throw ImageSourceError.Base64DecodeFailed()
+            }
+        }
+        // Non-base64: payload is percent-encoded text per RFC 2397.
+        return URLDecoder.decode(body, Charsets.UTF_8.name()).toByteArray(Charsets.UTF_8)
+    }
+
+    private fun fetchHttp(url: String, client: OkHttpClient): ByteArray {
+        client.newCall(Request.Builder().url(url).build()).execute().use { resp ->
+            if (!resp.isSuccessful) throw ImageSourceError.HttpError(resp.code)
+            return resp.body?.bytes() ?: ByteArray(0)
+        }
+    }
+}