catalyst-core 0.1.0-canary.9 → 0.2.0-beta.2

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

@@ -4,6 +4,7 @@ import android.content.Intent
 import android.os.Build
 import android.os.Bundle
 import android.util.Log
+import android.view.MotionEvent
 import android.view.WindowManager
 import androidx.activity.OnBackPressedCallback
 import androidx.appcompat.app.AppCompatActivity
@@ -14,6 +15,7 @@ import org.json.JSONObject
 import java.util.Properties
 import io.yourname.androidproject.databinding.ActivityMainBinding
 import io.yourname.androidproject.NativeBridge
+import io.yourname.androidproject.plugins.PluginBridge
 import io.yourname.androidproject.utils.BridgeUtils
 import io.yourname.androidproject.utils.KeyboardUtil
 import io.yourname.androidproject.utils.NetworkUtils
@@ -39,6 +41,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
 
     private lateinit var binding: ActivityMainBinding
     private lateinit var nativeBridge: NativeBridge
+    private lateinit var pluginBridge: PluginBridge
     private lateinit var customWebView: CustomWebView
     lateinit var properties: Properties
     private lateinit var metricsMonitor: MetricsMonitor
@@ -133,6 +136,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         "X-Safe-Area-Right" to latestSafeAreaInsets.right.toString(),
         "X-Safe-Area-Bottom" to latestSafeAreaInsets.bottom.toString(),
         "X-Safe-Area-Left" to latestSafeAreaInsets.left.toString(),
+        "X-Catalyst-Native-WebView" to "1",
         // Prevent caching of SSR response so updated headers are always used
         "Cache-Control" to "no-cache, no-store, must-revalidate",
         "Pragma" to "no-cache"
@@ -324,10 +328,23 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         try {
             nativeBridge = NativeBridge(this, customWebView.getWebView(), properties)
             customWebView.addJavascriptInterface(nativeBridge, "NativeBridge")
+
+            // Wire NativeCameraManager
+            val cameraManager = NativeCameraManager(this, binding.cameraPreview, customWebView.getWebView(), binding.debugViewfinderOverlay, binding.debugViewfinderOverlay.findViewById(R.id.debug_qr_status), binding.debugBarcodeOverlay)
+            nativeBridge.setCameraManager(cameraManager)
+            customWebView.onPageStarted = { cameraManager.stop() }
         } catch (e: Exception) {
             Log.e(TAG, "Failed to initialize NativeBridge: ${e.message}")
         }
 
+        // Setup isolated PluginBridge
+        try {
+            pluginBridge = PluginBridge(this, customWebView.getWebView(), properties)
+            customWebView.addJavascriptInterface(pluginBridge, "PluginBridge")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to initialize PluginBridge: ${e.message}")
+        }
+
         setupSafeAreaHandling()
 
         // Setup back press handler (modern API)
@@ -369,7 +386,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
                     if (BuildConfig.DEBUG) {
                         Log.w(TAG, "📴 Device offline on launch, showing offline page")
                     }
-                    customWebView.showOfflinePage()
+                    customWebView.showOfflineRouteOrOfflinePage(currentUrl)
                 }
             }
 
@@ -421,6 +438,13 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         customWebView.onResume()
     }
 
+    override fun dispatchTouchEvent(ev: MotionEvent): Boolean {
+        if (::nativeBridge.isInitialized) {
+            nativeBridge.getCameraManager()?.onTouchEvent(ev)
+        }
+        return super.dispatchTouchEvent(ev)
+    }
+
     override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
         super.onRequestPermissionsResult(requestCode, permissions, grantResults)
         if (::nativeBridge.isInitialized) {
@@ -445,11 +469,16 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         if (::keyboardUtil.isInitialized) {
             keyboardUtil.cleanup()
         }
-        if (::nativeBridge.isInitialized) {
-            nativeBridge.cleanup()
+        if (::customWebView.isInitialized) {
+            if (::pluginBridge.isInitialized) {
+                customWebView.removeJavascriptInterface("PluginBridge")
+            }
+            if (::nativeBridge.isInitialized) {
+                customWebView.removeJavascriptInterface("NativeBridge")
+            }
+            customWebView.destroy()
         }
         coroutineContext.cancelChildren()
-        customWebView.destroy()
         super.onDestroy()
     }
 
@@ -505,7 +534,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
                 loadUrlWithSafeArea(url)
             } else {
                 Log.w(TAG, "📴 Offline during notification click, showing offline page")
-                customWebView.showOfflinePage()
+                customWebView.showOfflineRouteOrOfflinePage(url)
             }
 
         } catch (e: Exception) {

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

@@ -151,9 +151,16 @@ class NativeBridge(
     
     private var networkMonitor: NetworkMonitor? = null
 
+    // Video stream manager
+    private var nativeCameraManager: NativeCameraManager? = null
+    private var webViewOriginalBackground: Int = android.graphics.Color.WHITE
+
     // Unified notification manager
     private val notificationManager = AppNotificationManager(mainActivity, mainActivity.properties)
 
+    // Transition manager — snapshot overlay pattern for native page transitions
+    private val transitionManager = TransitionManager(mainActivity, webView)
+
     companion object {
         private const val TAG = "NativeBridge"
         private const val GOOGLE_SIGN_IN_SAFE_EXECUTE_ACTION = "start Google Sign-In"
@@ -206,7 +213,7 @@ class NativeBridge(
                 .filter { it.isNotEmpty() }
 
             accessControlEnabled = properties
-                .getProperty("accessControl.enabled", "true")
+                .getProperty("accessControl.enabled", "false")
                 .equals("true", ignoreCase = true)
 
             if (accessControlEnabled && allowedUrls.isNotEmpty()) {
@@ -239,6 +246,90 @@ class NativeBridge(
         }
     }
 
+    fun setCameraManager(manager: NativeCameraManager) {
+        nativeCameraManager = manager
+    }
+
+    fun getCameraManager(): NativeCameraManager? = nativeCameraManager
+
+    @JavascriptInterface
+    fun startVideoStream(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "start video stream") {
+            android.util.Log.d("NativeBridge", "startVideoStream raw options: $optionsRaw")
+            val options = try { JSONObject(optionsRaw ?: "{}") } catch (e: Exception) { JSONObject() }
+            val facing = options.optString("facing", "back")
+            val viewfinderRect = options.optJSONObject("viewfinderRect")
+            val zoomOptions = options.optJSONObject("zoom")
+            val scanFormat = options.optString("format", "all")
+            val showQrDetected = options.optBoolean("showQrDetected", false)
+            android.util.Log.d("NativeBridge", "startVideoStream parsed: facing=$facing zoom=$zoomOptions scanFormat=$scanFormat viewfinderRect=$viewfinderRect showQrDetected=$showQrDetected")
+            mainActivity.runOnUiThread {
+                webViewOriginalBackground = webView.solidColor.takeIf { it != 0 } ?: android.graphics.Color.WHITE
+                webView.setBackgroundColor(android.graphics.Color.TRANSPARENT)
+                nativeCameraManager?.start(facing, viewfinderRect, zoomOptions, scanFormat, showQrDetected = showQrDetected)
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun stopVideoStream(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "stop video stream") {
+            mainActivity.runOnUiThread {
+                webView.setBackgroundColor(webViewOriginalBackground)
+                nativeCameraManager?.stop()
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun setVideoStreamZoom(multiplierRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "set video stream zoom") {
+            val multiplier = multiplierRaw?.trim()?.toFloatOrNull() ?: run {
+                android.util.Log.w("NativeBridge", "setVideoStreamZoom — invalid value: $multiplierRaw, ignoring")
+                return@safeExecute
+            }
+            android.util.Log.d("NativeBridge", "setVideoStreamZoom — multiplier=${multiplier}x")
+            mainActivity.runOnUiThread {
+                nativeCameraManager?.setZoom(multiplier)
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun setVideoStreamTorch(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "set video stream torch") {
+            val options = try { JSONObject(optionsRaw ?: "{}") } catch (e: Exception) { JSONObject() }
+            val on = options.optBoolean("on", false)
+            android.util.Log.d("NativeBridge", "setVideoStreamTorch — on=$on")
+            mainActivity.runOnUiThread {
+                nativeCameraManager?.setTorch(on)
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun setVideoStreamFps(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "set video stream fps") {
+            val options = try { JSONObject(optionsRaw ?: "{}") } catch (e: Exception) { JSONObject() }
+            val min = if (options.isNull("min")) null else options.optInt("min")
+            val max = if (options.isNull("max")) null else options.optInt("max")
+            android.util.Log.d("NativeBridge", "setVideoStreamFps — min=$min max=$max")
+            mainActivity.runOnUiThread {
+                nativeCameraManager?.setFps(min, max)
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun flipVideoStream(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "flip video stream") {
+            android.util.Log.d("NativeBridge", "flipVideoStream called")
+            mainActivity.runOnUiThread {
+                nativeCameraManager?.flip()
+            }
+        }
+    }
+
     @JavascriptInterface
     fun openCamera(options: String?) {
         BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "open camera") {
@@ -1023,6 +1114,17 @@ class NativeBridge(
      * Handle permission request results
      */
     fun handlePermissionResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
+        if (requestCode == NativeCameraManager.PERMISSION_REQUEST_CODE) {
+            val granted = grantResults.isNotEmpty() &&
+                grantResults[0] == android.content.pm.PackageManager.PERMISSION_GRANTED
+            val cam = nativeCameraManager
+            if (cam == null) {
+                Log.w(TAG, "handlePermissionResult — nativeCameraManager is null, ignoring camera permission result")
+                return
+            }
+            cam.onPermissionResult(granted)
+            return
+        }
         BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.NOTIFICATION_PERMISSION_STATUS, "handle permission result") {
             // Delegate to notification manager which handles notification permissions
             notificationManager.getNotificationUtils().handlePermissionResult(requestCode, permissions, grantResults)
@@ -1133,6 +1235,45 @@ class NativeBridge(
         }
     }
 
+    @JavascriptInterface
+    fun startTransition(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_TRANSITION_CANCELLED, "start transition") {
+            val options = try {
+                JSONObject(optionsRaw ?: "{}")
+            } catch (e: Exception) {
+                Log.w(TAG, "startTransition — malformed JSON, using defaults: $optionsRaw")
+                JSONObject()
+            }
+
+            val type = options.optString("type", "slide")
+            val direction = options.optString("direction", "left")
+            val duration = options.optInt("duration", 300).coerceIn(0, 2000)
+            val timeout = options.optInt("timeout", maxOf(duration * 3, 800))
+
+            mainActivity.runOnUiThread {
+                transitionManager.startTransition(type, direction, duration, timeout)
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun commitTransition(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_TRANSITION_CANCELLED, "commit transition") {
+            mainActivity.runOnUiThread {
+                transitionManager.commitTransition()
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun cancelTransition(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_TRANSITION_CANCELLED, "cancel transition") {
+            mainActivity.runOnUiThread {
+                transitionManager.cancelTransition()
+            }
+        }
+    }
+
     @JavascriptInterface
     fun getSafeArea(data: String? = null) {
         BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_SAFE_AREA_INSETS_UPDATED, "get safe area") {
@@ -1164,6 +1305,13 @@ class NativeBridge(
             // Cleanup NotificationManager
             notificationManager.cleanup()
 
+            // Cancel any in-flight transition and release overlay
+            transitionManager.cleanup()
+
+            // Stop video stream
+            nativeCameraManager?.cleanup()
+            nativeCameraManager = null
+
             // Stop network monitoring
             networkMonitor?.stop()
             networkMonitor = null

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"
+            }
+        }
+    }
+}