catalyst-core 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/NativeCameraManager.kt

@@ -0,0 +1,337 @@
+package io.yourname.androidproject
+
+import android.graphics.Color
+import android.graphics.RectF
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import android.view.MotionEvent
+import android.view.View
+import android.webkit.WebView
+import android.widget.TextView
+import androidx.camera.view.PreviewView
+import com.google.mlkit.vision.barcode.common.Barcode
+import io.yourname.androidproject.camera.*
+import io.yourname.androidproject.utils.BridgeUtils
+import org.json.JSONObject
+
+/**
+ * Thin facade — wires all camera sub-components and exposes the public API
+ * that NativeBridge.kt calls. All logic lives in the camera/ package.
+ */
+class NativeCameraManager(
+    private val activity: MainActivity,
+    private val previewView: PreviewView,
+    private val webView: WebView,
+    private val debugOverlay: View? = null,
+    private val debugQrStatus: TextView? = null,
+    private val debugBarcodeOverlay: View? = null
+) {
+
+    companion object {
+        private const val TAG = "NativeCameraManager"
+        const val PERMISSION_REQUEST_CODE = CameraSessionManager.PERMISSION_REQUEST_CODE
+
+        // QR overlay colors — change here to update both states
+        private const val COLOR_QR_IN_FRAME = "#5500FF00"  // green, semi-transparent
+        private const val COLOR_QR_DETECTED  = "#55FF6600"  // orange, semi-transparent
+        private const val OVERLAY_HIDE_DELAY_MS = 200L
+    }
+
+    private val stateMachine = VideoStreamStateMachine()
+
+    private val zoomController = ZoomController(
+        context = activity,
+        stateMachine = stateMachine,
+        onZoomChanged = { zoomLevel, minZoom, maxZoom ->
+            val payload = JSONObject().apply {
+                // zoomLevel = raw CameraX zoomRatio (1.0=1x, 2.0=2x)
+                put("zoomLevel", Math.round(zoomLevel * 10.0) / 10.0)
+                put("minZoom", Math.round(minZoom * 10.0) / 10.0)
+                put("maxZoom", Math.round(maxZoom * 10.0) / 10.0)
+            }
+            BridgeUtils.notifyWebJson(webView, BridgeUtils.WebEvents.ON_ZOOM_CHANGED, payload)
+            // Repaint overlay at new zoom level — barcode rect shifts as camera zooms
+            if (showQrDetected && overlayVisible) {
+                lastBarcodeScreenRect?.let { repaintQrOverlay(it, overlayIsOrange) }
+            }
+        }
+    )
+
+    private val torchController = TorchController(
+        context = activity,
+        onTorchChanged = { enabled ->
+            val payload = JSONObject().apply { put("enabled", enabled) }
+            BridgeUtils.notifyWebJson(webView, BridgeUtils.WebEvents.ON_TORCH_CHANGED, payload)
+        }
+    )
+
+    private val barcodeDetector = BarcodeDetector(
+        zoomController = zoomController,
+        onDetected = { barcode, imgW, imgH -> onBarcodeDetected(barcode, imgW, imgH) }
+    )
+
+    private val sessionManager = CameraSessionManager(
+        activity = activity,
+        previewView = previewView,
+        stateMachine = stateMachine,
+        zoomController = zoomController,
+        torchController = torchController,
+        barcodeDetector = barcodeDetector,
+        onReady = {
+            BridgeUtils.notifyWeb(webView, BridgeUtils.WebEvents.ON_VIDEO_STREAM_READY)
+        },
+        onStopped = {
+            debugOverlay?.let { activity.runOnUiThread { it.visibility = View.GONE } }
+            BridgeUtils.notifyWeb(webView, BridgeUtils.WebEvents.ON_VIDEO_STREAM_STOPPED)
+        },
+        onError = { message ->
+            BridgeUtils.notifyWebError(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, message)
+        }
+    )
+
+    private val holdController = HoldController(
+        stateMachine = stateMachine,
+        barcodeDetector = barcodeDetector
+    )
+
+    // Viewfinder state — written on main thread, read on analyzer thread
+    @Volatile private var viewfinderScreenRect: RectF? = null
+
+    // QR detected overlay state — written on analyzer thread, read on main thread and vice versa
+    @Volatile private var showQrDetected: Boolean = false
+    @Volatile private var overlayIsOrange: Boolean = false       // logical state — set before showQrOverlay
+    @Volatile private var overlayPaintedOrange: Boolean = false  // what color was last painted
+    @Volatile private var overlayVisible: Boolean = false
+    @Volatile private var lastBarcodeScreenRect: RectF? = null
+    private val overlayHideHandler = Handler(Looper.getMainLooper())
+    @Volatile private var overlayHideRunnable: Runnable? = null
+
+    init {
+        stateMachine.addListener(object : VideoStreamStateListener {
+            override fun onStateChanged(prev: VideoStreamState, next: VideoStreamState) {
+                // Reset overlay when hold ends (new scan cycle) or stream stops
+                if ((prev == VideoStreamState.HOLD && next == VideoStreamState.STREAMING) ||
+                    next == VideoStreamState.IDLE || next == VideoStreamState.STOPPING
+                ) {
+                    hideQrOverlay()
+                }
+            }
+        })
+    }
+
+    // ---- Public API (called from NativeBridge) ----
+
+    fun start(facing: String = "back", viewfinderRectJson: JSONObject? = null, zoomOptions: JSONObject? = null, scanFormat: String = "all", fpsMin: Int? = null, fpsMax: Int? = null, showQrDetected: Boolean = false) {
+        if (stateMachine.isActive) return
+
+        this.showQrDetected = showQrDetected
+        this.overlayIsOrange = false
+        this.overlayPaintedOrange = false
+        this.overlayVisible = false
+        this.lastBarcodeScreenRect = null
+
+        val autoZoom = zoomOptions?.optBoolean("auto", false) ?: false
+        val initialZoomPct = zoomOptions?.optDouble("initial", 1.0)?.toFloat() ?: 1.0f
+
+        // Parse viewfinder rect and position debug overlay
+        viewfinderRectJson?.let { json ->
+            val result = ViewfinderMapper.parseViewfinderRect(json, webView)
+            viewfinderScreenRect = result?.first
+            result?.second?.let { jsRect -> positionDebugOverlay(jsRect) }
+        } ?: run {
+            viewfinderScreenRect = null
+            Log.w(TAG, "No viewfinderRect — all QR codes will be reported")
+        }
+
+        stateMachine.transition(VideoStreamState.STARTING)
+        sessionManager.start(
+            facing = facing,
+            autoZoom = autoZoom,
+            initialZoomPct = initialZoomPct,  // now Float multiplier (1.0 = 1x)
+            scanFormat = scanFormat,
+            fpsMin = fpsMin,
+            fpsMax = fpsMax
+        )
+    }
+
+    fun stop() {
+        if (!stateMachine.isActive) return
+        holdController.reset()
+        stateMachine.transition(VideoStreamState.STOPPING)
+        sessionManager.stop()
+    }
+
+    fun flip() {
+        if (!stateMachine.isActive) return
+        holdController.reset()
+        stateMachine.transition(VideoStreamState.FLIPPING)
+        sessionManager.flip()
+    }
+
+    fun setZoom(multiplier: Float) = zoomController.setZoom(multiplier)
+
+    fun setTorch(on: Boolean) = torchController.setTorch(on)
+
+    fun setFps(min: Int?, max: Int?) {
+        if (!stateMachine.isActive) return
+        sessionManager.setFps(min, max)
+    }
+
+    fun onTouchEvent(event: MotionEvent): Boolean = zoomController.onTouchEvent(event)
+
+    fun onPermissionResult(granted: Boolean) = sessionManager.onPermissionResult(granted)
+
+    fun cleanup() {
+        overlayHideRunnable?.let { overlayHideHandler.removeCallbacks(it) }
+        overlayHideRunnable = null
+        sessionManager.cleanup()
+    }
+
+    // ---- Detection handler ----
+
+    private fun onBarcodeDetected(barcode: Barcode, imageWidth: Int, imageHeight: Int) {
+        val value = barcode.rawValue ?: return
+
+        // Hold gate — defensive check for in-flight frames
+        if (stateMachine.state == VideoStreamState.HOLD) {
+            Log.d(TAG, "onBarcodeDetected — in hold, skipping: $value")
+            return
+        }
+
+        // QR overlay — show green immediately (QR in frame), update position each frame
+        val barcodeScreenRect = barcode.boundingBox?.let { box ->
+            ViewfinderMapper.mapBarcodeToScreen(
+                box.left, box.top, box.right, box.bottom,
+                imageWidth, imageHeight,
+                previewView.width.toFloat(), previewView.height.toFloat()
+            )
+        }
+        if (showQrDetected && barcodeScreenRect != null) {
+            showQrOverlay(barcodeScreenRect, orange = overlayIsOrange)
+        }
+
+        // Viewfinder region filter
+        val regionRect = viewfinderScreenRect
+        if (regionRect != null) {
+            if (barcodeScreenRect != null) {
+                if (!regionRect.contains(barcodeScreenRect)) {
+                    updateDebugQrStatus(inside = false)
+                    return
+                }
+                updateDebugQrStatus(inside = true)
+            }
+        }
+
+        // Same-value dedup — enter hold either way
+        if (!holdController.isNewValue(value)) {
+            Log.d(TAG, "onBarcodeDetected — same value, suppressing: $value")
+            holdController.startHold()
+            return
+        }
+
+        // New value confirmed — flip overlay to orange before firing event
+        if (showQrDetected && barcodeScreenRect != null) {
+            overlayIsOrange = true
+            showQrOverlay(barcodeScreenRect, orange = true)
+        }
+
+        holdController.startHold()
+
+        val payload = JSONObject().apply {
+            put("value", value)
+            put("format", BarcodeDetector.formatName(barcode.format))
+        }
+        BridgeUtils.notifyWebJson(webView, BridgeUtils.WebEvents.ON_QR_DETECTED, payload)
+        Log.d(TAG, "QR detected (new): $value")
+    }
+
+    // ---- QR detected overlay ----
+
+    /**
+     * Called on every ML Kit frame that has a barcode.
+     * If overlay is already visible: only reschedule the hide — no layout/color update (prevents flicker).
+     * If overlay is not visible: position it, set color, show it.
+     * lastBarcodeScreenRect is always updated so zoom repaints use the freshest position.
+     */
+    private fun showQrOverlay(screenRect: RectF, orange: Boolean) {
+        lastBarcodeScreenRect = screenRect
+
+        // Reschedule hide regardless
+        overlayHideRunnable?.let { overlayHideHandler.removeCallbacks(it) }
+        val hideRunnable = Runnable { hideQrOverlayOnUiThread() }
+        overlayHideRunnable = hideRunnable
+        overlayHideHandler.postDelayed(hideRunnable, OVERLAY_HIDE_DELAY_MS)
+
+        if (overlayVisible && orange == overlayPaintedOrange) return  // already painted at correct color — skip to prevent flicker
+
+        repaintQrOverlay(screenRect, orange)
+    }
+
+    /**
+     * Force-reposition and repaint the overlay. Called on first show and on zoom change.
+     * screenRect is in PreviewView/RelativeLayout space — no offset adjustment needed.
+     */
+    private fun repaintQrOverlay(screenRect: RectF, orange: Boolean) {
+        val color = Color.parseColor(if (orange) COLOR_QR_DETECTED else COLOR_QR_IN_FRAME)
+        overlayVisible = true
+        overlayPaintedOrange = orange
+        activity.runOnUiThread {
+            debugBarcodeOverlay?.let { overlay ->
+                val lp = overlay.layoutParams as? android.widget.RelativeLayout.LayoutParams ?: return@runOnUiThread
+                lp.leftMargin = screenRect.left.toInt()
+                lp.topMargin  = screenRect.top.toInt()
+                lp.width      = screenRect.width().toInt()
+                lp.height     = screenRect.height().toInt()
+                overlay.layoutParams = lp
+                overlay.setBackgroundColor(color)
+                overlay.visibility = View.VISIBLE
+            }
+        }
+    }
+
+    private fun hideQrOverlay() {
+        overlayHideRunnable?.let { overlayHideHandler.removeCallbacks(it) }
+        overlayHideRunnable = null
+        overlayIsOrange = false
+        overlayPaintedOrange = false
+        lastBarcodeScreenRect = null
+        hideQrOverlayOnUiThread()
+    }
+
+    private fun hideQrOverlayOnUiThread() {
+        overlayVisible = false
+        activity.runOnUiThread {
+            debugBarcodeOverlay?.visibility = View.GONE
+        }
+    }
+
+    // ---- Debug overlay helpers ----
+
+    private fun positionDebugOverlay(jsRect: RectF) {
+        activity.runOnUiThread {
+            debugOverlay?.let { overlay ->
+                val lp = overlay.layoutParams as? android.widget.RelativeLayout.LayoutParams ?: return@runOnUiThread
+                lp.leftMargin = jsRect.left.toInt()
+                lp.topMargin = jsRect.top.toInt()
+                lp.width = jsRect.width().toInt()
+                lp.height = jsRect.height().toInt()
+                overlay.layoutParams = lp
+                overlay.setBackgroundResource(R.drawable.debug_viewfinder_border)
+                overlay.visibility = View.VISIBLE
+            }
+        }
+    }
+
+    private fun updateDebugQrStatus(inside: Boolean) {
+        activity.runOnUiThread {
+            if (inside) {
+                debugQrStatus?.setTextColor(Color.parseColor("#34C759"))
+                debugQrStatus?.text = "⬤ QR inside"
+            } else {
+                debugQrStatus?.setTextColor(Color.parseColor("#FF3B30"))
+                debugQrStatus?.text = "⬤ QR outside"
+            }
+        }
+    }
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/TransitionManager.kt

@@ -0,0 +1,202 @@
+package io.yourname.androidproject
+
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
+import android.animation.ValueAnimator
+import android.app.Activity
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import android.view.View
+import android.view.ViewGroup
+import android.webkit.WebView
+import android.widget.FrameLayout
+import android.widget.ImageView
+import io.yourname.androidproject.utils.BridgeUtils
+
+/**
+ * Manages native page transitions using a snapshot-overlay pattern.
+ *
+ * Flow:
+ *   startTransition()  — captures a bitmap of the current WebView, places it as an
+ *                        ImageView overlay on top of the content, covering the skeleton
+ *                        rendered by the router while the new page loads.
+ *   commitTransition() — animates the overlay out (slide or fade) to reveal the new page.
+ *   cancelTransition() — removes the overlay immediately without animating.
+ *
+ * Safety timer: a Handler timer fires on the main thread after `timeout` ms if
+ *   commitTransition() was never called (JS error/hang). It force-fades the overlay
+ *   and fires ON_TRANSITION_TIMEOUT to JS so the hook can reset its state.
+ *
+ * Thread safety: all public methods must be called on the main thread.
+ */
+class TransitionManager(
+    private val activity: Activity,
+    private val webView: WebView
+) {
+    private val TAG = "TransitionManager"
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    private var overlayView: ImageView? = null
+    private var safetyRunnable: Runnable? = null
+    private var activeDuration: Int = 300
+    private var activeType: String = "slide"
+    private var activeDirection: String = "left"
+
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+
+    fun startTransition(type: String, direction: String, duration: Int, timeout: Int) {
+        // Cancel any orphaned transition first
+        cancelTransitionInternal(notify = false)
+
+        activeType = type
+        activeDirection = direction
+        activeDuration = duration
+
+        val snapshot = captureSnapshot() ?: run {
+            Log.w(TAG, "startTransition — snapshot failed, transition skipped")
+            return
+        }
+
+        val overlay = ImageView(activity).apply {
+            setImageBitmap(snapshot)
+            layoutParams = ViewGroup.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT,
+                ViewGroup.LayoutParams.MATCH_PARENT
+            )
+            scaleType = ImageView.ScaleType.MATRIX
+        }
+
+        val root = activity.window.decorView as ViewGroup
+        root.addView(overlay)
+        overlayView = overlay
+
+        Log.d(TAG, "startTransition — overlay attached (type=$type direction=$direction duration=${duration}ms timeout=${timeout}ms)")
+
+        // Arm safety timer
+        val safety = Runnable {
+            Log.w(TAG, "startTransition — safety timeout fired, force-removing overlay")
+            cancelTransitionInternal(notify = false)
+            BridgeUtils.notifyWebSuccess(webView, BridgeUtils.WebEvents.ON_TRANSITION_TIMEOUT)
+        }
+        safetyRunnable = safety
+        mainHandler.postDelayed(safety, timeout.toLong())
+    }
+
+    fun commitTransition() {
+        val overlay = overlayView ?: run {
+            Log.w(TAG, "commitTransition — no active overlay, ignoring")
+            return
+        }
+
+        // Disarm safety timer — we're committing normally
+        disarmSafetyTimer()
+
+        when (activeType) {
+            "fade" -> animateFadeOut(overlay, activeDuration)
+            else -> animateSlideOut(overlay, activeDuration, activeDirection)
+        }
+    }
+
+    fun cancelTransition() {
+        cancelTransitionInternal(notify = true)
+    }
+
+    fun cleanup() {
+        cancelTransitionInternal(notify = false)
+    }
+
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+
+    private fun captureSnapshot(): Bitmap? {
+        return try {
+            val bmp = Bitmap.createBitmap(webView.width, webView.height, Bitmap.Config.ARGB_8888)
+            val canvas = Canvas(bmp)
+            webView.draw(canvas)
+            bmp
+        } catch (e: Exception) {
+            Log.e(TAG, "captureSnapshot failed", e)
+            null
+        }
+    }
+
+    private fun animateSlideOut(overlay: ImageView, duration: Int, direction: String) {
+        val root = activity.window.decorView as ViewGroup
+        val w = root.width.toFloat()
+        val h = root.height.toFloat()
+
+        val (endX, endY) = when (direction) {
+            "right" -> Pair(-w, 0f)
+            "up"    -> Pair(0f, h)
+            "down"  -> Pair(0f, -h)
+            else    -> Pair(w, 0f)   // "left" — overlay slides out to the right
+        }
+
+        ValueAnimator.ofFloat(0f, 1f).apply {
+            this.duration = duration.toLong()
+            addUpdateListener { anim ->
+                val fraction = anim.animatedFraction
+                overlay.translationX = endX * fraction
+                overlay.translationY = endY * fraction
+            }
+            addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    removeOverlay(overlay)
+                    BridgeUtils.notifyWebSuccess(webView, BridgeUtils.WebEvents.ON_TRANSITION_COMMITTED)
+                }
+            })
+            start()
+        }
+    }
+
+    private fun animateFadeOut(overlay: ImageView, duration: Int) {
+        ValueAnimator.ofFloat(1f, 0f).apply {
+            this.duration = duration.toLong()
+            addUpdateListener { anim ->
+                overlay.alpha = anim.animatedValue as Float
+            }
+            addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    removeOverlay(overlay)
+                    BridgeUtils.notifyWebSuccess(webView, BridgeUtils.WebEvents.ON_TRANSITION_COMMITTED)
+                }
+            })
+            start()
+        }
+    }
+
+    private fun cancelTransitionInternal(notify: Boolean) {
+        disarmSafetyTimer()
+
+        overlayView?.let { overlay ->
+            removeOverlay(overlay)
+            if (notify) {
+                BridgeUtils.notifyWebSuccess(webView, BridgeUtils.WebEvents.ON_TRANSITION_CANCELLED)
+            }
+        }
+    }
+
+    private fun removeOverlay(overlay: ImageView) {
+        try {
+            val root = activity.window.decorView as ViewGroup
+            root.removeView(overlay)
+        } catch (e: Exception) {
+            Log.w(TAG, "removeOverlay — view already detached: ${e.message}")
+        }
+        if (overlayView === overlay) {
+            overlayView = null
+        }
+        overlay.setImageBitmap(null)
+    }
+
+    private fun disarmSafetyTimer() {
+        safetyRunnable?.let { mainHandler.removeCallbacks(it) }
+        safetyRunnable = null
+    }
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/WebCacheManager.kt

@@ -404,12 +404,12 @@ class WebCacheManager(private val context: Context, private val properties: java
 
     private fun generateCacheKey(url: String): String {
         try {
-            val md = MessageDigest.getInstance("MD5")
+            val md = MessageDigest.getInstance("SHA-256")
             val digest = md.digest(url.toByteArray())
             return digest.joinToString("") { "%02x".format(it) }
         } catch (e: Exception) {
             Log.e(TAG, "Error generating cache key: ${e.message}")
-            // Fallback to a simple hash code if MD5 fails
+            // Fallback to a simple hash code if SHA-256 fails
             return url.hashCode().toString()
         }
     }
@@ -459,4 +459,4 @@ class WebCacheManager(private val context: Context, private val properties: java
             )
         }
     }
-}
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/camera/BarcodeDetector.kt

@@ -0,0 +1,123 @@
+package io.yourname.androidproject.camera
+
+import android.util.Log
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.core.ImageProxy
+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.ZoomSuggestionOptions
+import com.google.mlkit.vision.barcode.common.Barcode
+import com.google.mlkit.vision.common.InputImage
+import java.util.concurrent.ExecutorService
+
+/**
+ * Wraps ML Kit barcode scanning.
+ * Builds the scanner with format filter and optional auto-zoom.
+ * Fires [onDetected] for each barcode found in a frame.
+ */
+class BarcodeDetector(
+    private val zoomController: ZoomController,
+    private val onDetected: (barcode: Barcode, imageWidth: Int, imageHeight: Int) -> Unit
+) {
+
+    private val TAG = "BarcodeDetector"
+
+    private var scanner: BarcodeScanner? = null
+
+    /** When true, frames are still analyzed (no flicker) but results are not forwarded. */
+    @Volatile var suppressResults = false
+
+    /** scan: "qr" | "barcode" | "all" */
+    fun buildImageAnalysis(
+        executor: ExecutorService,
+        resolutionSelector: androidx.camera.core.resolutionselector.ResolutionSelector,
+        autoZoomEnabled: Boolean,
+        scanFormat: String
+    ): ImageAnalysis {
+        val formats = resolveFormats(scanFormat)
+        val optionsBuilder = BarcodeScannerOptions.Builder()
+            .setBarcodeFormats(formats.first(), *formats.drop(1).toIntArray())
+
+        if (autoZoomEnabled) {
+            Log.d(TAG, "Auto-zoom enabled, wiring ZoomSuggestionOptions")
+            optionsBuilder.setZoomSuggestionOptions(
+                ZoomSuggestionOptions.Builder { suggestedRatio ->
+                    zoomController.onAutoZoomSuggestion(suggestedRatio)
+                }
+                .setMaxSupportedZoomRatio(zoomController.currentMaxZoomRatio())
+                .build()
+            )
+        }
+
+        scanner?.close()
+        val newScanner = BarcodeScanning.getClient(optionsBuilder.build())
+        scanner = newScanner
+
+        return ImageAnalysis.Builder()
+            .setResolutionSelector(resolutionSelector)
+            .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+            .build()
+            .also { analysis ->
+                // Capture newScanner (not the field) so this analyzer always uses
+                // the scanner instance that was live when buildImageAnalysis() ran.
+                analysis.setAnalyzer(executor) { imageProxy ->
+                    processFrame(imageProxy, newScanner)
+                }
+            }
+    }
+
+    fun close() {
+        scanner?.close()
+        scanner = null
+    }
+
+    private fun processFrame(imageProxy: ImageProxy, activeScanner: BarcodeScanner) {
+        val mediaImage = imageProxy.image
+        if (mediaImage == null) {
+            imageProxy.close()
+            return
+        }
+        val rotDeg = imageProxy.imageInfo.rotationDegrees
+        val image = InputImage.fromMediaImage(mediaImage, rotDeg)
+        // Swap w/h for 90°/270° — ML Kit boxes are in post-rotation space
+        val imgW = if (rotDeg == 90 || rotDeg == 270) imageProxy.height else imageProxy.width
+        val imgH = if (rotDeg == 90 || rotDeg == 270) imageProxy.width else imageProxy.height
+
+        activeScanner.process(image)
+            .addOnSuccessListener { barcodes ->
+                if (!suppressResults) {
+                    barcodes.forEach { onDetected(it, imgW, imgH) }
+                }
+            }
+            .addOnFailureListener { e -> Log.w(TAG, "Barcode processing failed", e) }
+            .addOnCompleteListener { imageProxy.close() }
+    }
+
+    private fun resolveFormats(scan: String): List<Int> = when (scan) {
+        "qr"      -> listOf(Barcode.FORMAT_QR_CODE)
+        "barcode" -> listOf(
+            Barcode.FORMAT_EAN_13, Barcode.FORMAT_EAN_8,
+            Barcode.FORMAT_CODE_128, Barcode.FORMAT_CODE_39,
+            Barcode.FORMAT_UPC_A, Barcode.FORMAT_UPC_E,
+            Barcode.FORMAT_PDF417
+        )
+        else      -> listOf(Barcode.FORMAT_ALL_FORMATS)
+    }
+
+    companion object {
+        fun formatName(format: Int): String = when (format) {
+            Barcode.FORMAT_QR_CODE    -> "QR"
+            Barcode.FORMAT_EAN_13     -> "EAN_13"
+            Barcode.FORMAT_EAN_8      -> "EAN_8"
+            Barcode.FORMAT_CODE_128   -> "CODE_128"
+            Barcode.FORMAT_CODE_39    -> "CODE_39"
+            Barcode.FORMAT_DATA_MATRIX -> "DATA_MATRIX"
+            Barcode.FORMAT_PDF417     -> "PDF417"
+            Barcode.FORMAT_AZTEC      -> "AZTEC"
+            Barcode.FORMAT_UPC_A      -> "UPC_A"
+            Barcode.FORMAT_UPC_E      -> "UPC_E"
+            else                      -> "UNKNOWN"
+        }
+    }
+}