fix(setup): warm ML Kit barcode scanner at startup (v0.2.4.6-alpha)

Squash-merge of #53.

Author: robster7674

CLAUDE.md

@@ -13,8 +13,29 @@ If an upstream merge changes either of these, revert immediately and do not ship
 
 ## Git workflow
 
-After completing any fix or feature on the `glucodroid` branch, always commit and push the changes immediately.
-Use a clear commit message, then run `git push`.
+Never push directly to `origin/glucodroid`. All fixes and features go through a PR:
+
+1. Create a feature branch off `glucodroid` (e.g. `fix/<short-name>` or `feat/<short-name>`).
+2. Commit the changes on that branch.
+3. Push the feature branch: `git push -u origin <branch>`.
+4. Open a PR with `gh pr create --base glucodroid --head <branch> --title "..." --body "..."`.
+5. Merge with `gh pr merge <n> --squash --delete-branch` once CI is green.
+6. The `glucodroid` branch itself is updated by the squash merge — never `git push` to it directly.
+
+`origin` is `robster7674/glucodroid` (this repo). `upstream` is `ctqvva/JugglucoNG` — **never push to upstream** under any circumstances; it is read-only mirror reference.
+
+## Release process
+
+Every release follows these steps in order — do not skip any:
+
+1. Bump `versionName` / `versionCode` in `Common/build.gradle` defaultConfig.
+2. Build: `./gradlew assembleMobileLibre3SiDexNogoogleRelease -Pno_x86 -Pno_x86_64`.
+3. Copy APK to `~/Downloads/glucodroid.apk` (exact filename — never rename).
+4. Commit the version bump + any other release-blocker fixes on the feature branch.
+5. Open and merge the PR into `glucodroid` (squash, delete branch).
+6. Tag the merged commit on `glucodroid`: `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`.
+7. Create the GitHub release with `gh release create vX.Y.Z --prerelease --title "vX.Y.Z" --notes-file <notes.md> --target glucodroid`. (If `gh release create` fails on scope, use the REST API with `gh auth token`.)
+8. **Upload the APK as a release asset** — `~/Downloads/glucodroid.apk` MUST be attached to the release as `glucodroid.apk`. A release with notes but no APK is incomplete and the release is not done. Verify `browser_download_url` is present in the upload response.
 
 ## Fresh clone setup
 

Common/build.gradle

@@ -89,8 +89,8 @@ android {
         //compileSdk 36
         applicationId "cloud.glucodroid"
 
-         versionName '0.2.4.5'
-        versionCode 8245
+         versionName '0.2.4.6'
+        versionCode 8246
 //    multiDexEnabled true
 
         buildConfigField 'String', 'BUILD_TIME', 'new java.text.SimpleDateFormat("HH:mm:ss dd-MMM-yyyy").format(new java.util.Date(' + System.currentTimeMillis() + 'L))'

Common/src/main/java/tk/glucodata/MainActivity.java

@@ -478,6 +478,8 @@ protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         thisone = this;
 
+        warmUpBarcodeScanner();
+
         if (android.os.Build.VERSION.SDK_INT >= 21) {
             Log.i(LOG_ID, "sdk 21 or larger");
         } else {
@@ -545,6 +547,50 @@ private void initComposeUI() {
         }
     }
 
+    // Warm the ML Kit BarcodeScanning static holder on the main thread, before
+    // any wizard/Compose measure pass can reach it. The standalone ML Kit barcode
+    // scanner (com.google.mlkit:barcode-scanning) statically delegates to
+    // play-services-mlkit-barcode-scanning on the first BarcodeScanning.getClient
+    // call; calling it from a Compose `remember { }` block that is also being
+    // measured can race with the static initializer and NPE on the `zzi` field of
+    // the internal `zzg` holder (see FINDINGS / agent rule for the
+    // "standalone-MLKit initialization race"). Calling once here, in onCreate,
+    // and closing immediately, makes the static `zzg.INSTANCE` non-null and its
+    // `zza` field set, so subsequent wizard calls see a fully-initialized
+    // scanner. Reflective on purpose: the mlkit classes are not on the classpath
+    // of every flavor (no-google/wear), and a hard import would break those.
+    private void warmUpBarcodeScanner() {
+        try {
+            Class<?> scanningCls = Class.forName("com.google.mlkit.vision.barcode.BarcodeScanning");
+            Class<?> optionsCls = Class.forName("com.google.mlkit.vision.barcode.BarcodeScannerOptions");
+            Class<?> optionsBuilderCls = Class.forName("com.google.mlkit.vision.barcode.BarcodeScannerOptions$Builder");
+            Class<?> barcodeCls = Class.forName("com.google.mlkit.vision.barcode.common.Barcode");
+            Object options = optionsBuilderCls.getMethod("build").invoke(
+                optionsBuilderCls.getMethod("setBarcodeFormats", int[].class).invoke(
+                    optionsBuilderCls.getConstructor().newInstance(),
+                    new Object[]{ new int[]{
+                        barcodeCls.getField("FORMAT_QR_CODE").getInt(null),
+                        barcodeCls.getField("FORMAT_DATA_MATRIX").getInt(null)
+                    } }
+                )
+            );
+            Object scanner = scanningCls.getMethod("getClient", optionsCls).invoke(null, options);
+            try {
+                scanner.getClass().getMethod("close").invoke(scanner);
+            } catch (Throwable closeEx) {
+                // best-effort
+            }
+            Log.i(LOG_ID, "ML Kit barcode scanner warmed up");
+        } catch (ClassNotFoundException e) {
+            // mlkit not on classpath for this flavor; nothing to do
+            Log.i(LOG_ID, "ML Kit barcode scanner not present on classpath; skipping warm-up");
+        } catch (Throwable t) {
+            // Any init failure must not break app startup. The wizard's own
+            // runCatching will surface this to the user as a scanner error.
+            Log.w(LOG_ID, "ML Kit barcode scanner warm-up failed: " + t);
+        }
+    }
+
     // GestureDetector mGestureDetector;
     void handleIntent(Intent intent) {
         if (intent == null)

Common/src/mobile/java/tk/glucodata/ui/setup/InlineQrScannerCard.kt

@@ -61,6 +61,7 @@ import androidx.compose.ui.viewinterop.AndroidView
 import androidx.core.content.ContextCompat
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleEventObserver
+import com.google.mlkit.vision.barcode.BarcodeScanner
 import com.google.mlkit.vision.barcode.BarcodeScannerOptions
 import com.google.mlkit.vision.barcode.BarcodeScanning
 import com.google.mlkit.vision.barcode.common.Barcode
@@ -69,6 +70,7 @@ import java.util.concurrent.Executors
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicInteger
+import tk.glucodata.Log
 import tk.glucodata.R
 
 private fun Context.hasCameraPermission(): Boolean {
@@ -130,7 +132,7 @@ fun InlineQrScannerCard(
             )
             .build()
     }
-    val barcodeScanner = remember { BarcodeScanning.getClient(scannerOptions) }
+    var barcodeScanner by remember { mutableStateOf<BarcodeScanner?>(null) }
 
     val permissionLauncher = rememberLauncherForActivityResult(
         contract = ActivityResultContracts.RequestPermission()
@@ -144,6 +146,23 @@ fun InlineQrScannerCard(
         }
     }
 
+    // Defer BarcodeScanning.getClient() out of the measure pass into a coroutine.
+    // Doing this in `remember { }` races the lib's static <clinit> with Compose
+    // measure on cold start and can NPE on the `zzi` field of the internal
+    // `zzg` holder (see "standalone-MLKit initialization race" in
+    // ~/.config/kilo/agent/glucodroid.md). MainActivity warm-up runs once at
+    // process start; this LaunchedEffect is the per-composable safety net that
+    // also recovers from a warm-up failure by surfacing it to `scannerError`.
+    LaunchedEffect(Unit) {
+        if (barcodeScanner != null) return@LaunchedEffect
+        runCatching { BarcodeScanning.getClient(scannerOptions) }
+            .onSuccess { barcodeScanner = it }
+            .onFailure { t ->
+                scannerError = t.message ?: t.javaClass.simpleName
+                Log.e("InlineQrScannerCard", "Failed to acquire ML Kit barcode scanner: ${t.message}")
+            }
+    }
+
     DisposableEffect(Unit) {
         onDispose {
             if (touchActive) {
@@ -153,7 +172,8 @@ fun InlineQrScannerCard(
             camera = null
             torchEnabled = false
             analyzerExecutor.shutdown()
-            barcodeScanner.close()
+            barcodeScanner?.close()
+            barcodeScanner = null
         }
     }
 
@@ -210,7 +230,8 @@ fun InlineQrScannerCard(
                             .also { imageAnalysis ->
                                 imageAnalysis.setAnalyzer(analyzerExecutor) { imageProxy ->
                                     val mediaImage = imageProxy.image
-                                    if (mediaImage == null || consumed) {
+                                    val scanner = barcodeScanner
+                                    if (mediaImage == null || consumed || scanner == null) {
                                         imageProxy.close()
                                         return@setAnalyzer
                                     }
@@ -224,7 +245,7 @@ fun InlineQrScannerCard(
                                         imageProxy.imageInfo.rotationDegrees
                                     )
 
-                                    barcodeScanner.process(inputImage)
+                                    scanner.process(inputImage)
                                         .addOnSuccessListener(mainExecutor) { barcodes ->
                                             val rawValue = barcodes
                                                 .firstNotNullOfOrNull { it.rawValue?.trim()?.takeIf { value -> value.isNotEmpty() } }