catalyst-core 0.1.0-canary.8 → 0.2.0-beta.1

package/README.md

@@ -14,7 +14,7 @@
 
 Catalyst offers a comprehensive suite of features designed for modern web development. It includes isomorphic rendering for optimal performance, an extendable server with full-stack capabilities, and configurable state management. The framework employs smart prefetching of data and chunks, allows easy configuration of global styles and layouts, and provides SEO optimization at both global and page levels.
 
-This version adds support for Universal app for both Android and iOS. Please checkout [Universal App Documentaion](https://catalyst.1mg.com/public_docs/content/Universal%20App/RunUniversalApp)
+Catalyst also supports universal apps for Android and iOS. See the [Universal App guide](https://catalyst.1mg.com/public_docs/content/Guides%20and%20Tutorials/First%20Universal%20App/first-universal-app) to get started.
 
 ## Installation
 

package/changelog.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.0-beta.2] - 2026-05-06
+
+- Moved Catalyst into a monorepo structure with `catalyst-core`, `create-catalyst-app`, the Catalyst docs app, and the Catalyst core test app managed from one repository.
+- Replaced the internal-package pre-release flow with a local release sandbox that scaffolds a real app using current-branch CCA and a locally packed current-branch `catalyst-core`.
+
 ## [0.1.0-canary.8] - 2026-04-15
 
 - Introduced Catalyst’s internal plugin architecture, adding the `PluginBridge` web API, native plugin runtimes for Android and iOS, and manifest-driven build composition for modular native capabilities.

package/dist/native/androidProject/app/build.gradle.kts

@@ -208,6 +208,15 @@ dependencies {
     // SLF4J simple logger for Ktor (optional, can be excluded if needed)
     implementation("org.slf4j:slf4j-simple:2.0.9")
 
+    // CameraX
+    implementation("androidx.camera:camera-core:1.3.4")
+    implementation("androidx.camera:camera-camera2:1.3.4")
+    implementation("androidx.camera:camera-lifecycle:1.3.4")
+    implementation("androidx.camera:camera-view:1.3.4")
+
+    // ML Kit Barcode Scanning
+    implementation("com.google.mlkit:barcode-scanning:17.3.0")
+
     // Notification dependencies - conditional based on config
     if (isNotificationsEnabled()) {
         implementation("androidx.localbroadcastmanager:localbroadcastmanager:1.1.0")

package/dist/native/androidProject/app/src/main/AndroidManifest.xml

@@ -24,6 +24,7 @@
         android:usesCleartextTraffic="true"
         android:networkSecurityConfig="@xml/network_security_config"
         tools:targetApi="31">
+        <!-- nosemgrep: java.android.security.exported_activity.exported_activity - Launcher activity must be exported so Android can start the app from the launcher. -->
         <activity
             android:name="io.yourname.androidproject.SplashActivity"
             android:exported="true"
@@ -51,4 +52,4 @@
         </provider>
     </application>
 
-</manifest>
+</manifest>

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

@@ -51,6 +51,7 @@ class CustomWebView(
     private var offlinePageVisible = false
     private var lastTargetUrl: String? = null
     private var defaultRequestHeaders: Map<String, String> = emptyMap()
+    var onPageStarted: (() -> Unit)? = null
 
     // Counters for asset loading statistics
     private var assetLoadAttempts = 0
@@ -464,6 +465,18 @@ class CustomWebView(
         return "build/public/$fileName"
     }
 
+    private fun withCorsHeaders(response: WebResourceResponse): WebResourceResponse {
+        val responseHeaders = response.responseHeaders
+        if (responseHeaders.isNullOrEmpty()) {
+            response.responseHeaders = mutableMapOf(
+                "Access-Control-Allow-Origin" to "*",
+                "Access-Control-Allow-Methods" to "GET, OPTIONS",
+                "Access-Control-Allow-Headers" to "*"
+            )
+        }
+        return response
+    }
+
     private fun getMimeType(path: String): String {
         return when {
             path.endsWith(".html") -> "text/html"
@@ -532,7 +545,7 @@ class CustomWebView(
                                 if (BuildConfig.DEBUG) {
                                     Log.d(TAG, "✅ SERVICE_WORKER: Served from cache: $url")
                                 }
-                                response
+                                withCorsHeaders(response)
                             } else {
                                 if (BuildConfig.DEBUG) {
                                     Log.d(TAG, "❌ SERVICE_WORKER: Cache miss: $url")
@@ -617,6 +630,9 @@ class CustomWebView(
             domStorageEnabled = true
             allowFileAccess = true
             allowContentAccess = true
+            setSupportZoom(false)
+            builtInZoomControls = false
+            displayZoomControls = false
 
             // TODO: Enable these when build optimization feature is implemented
             // These are deprecated but may be needed for local file access in development
@@ -823,7 +839,7 @@ class CustomWebView(
                                 Log.d(TAG, "✅ WEBVIEW_CLIENT: Served from cache in ${duration}ms: $url")
                             }
                             metricsMonitor.recordCacheHit(url)
-                            return response
+                            return withCorsHeaders(response)
                         } else {
                             if (BuildConfig.DEBUG) {
                                 Log.d(TAG, "❌ WEBVIEW_CLIENT: Cache miss, triggering async fetch: $url")
@@ -893,6 +909,7 @@ class CustomWebView(
                 super.onPageStarted(view, url, favicon)
                 if (url != null && url != offlineAssetUrl) {
                     offlinePageVisible = false
+                    onPageStarted?.invoke()
                 }
                 progressBar.visibility = View.VISIBLE
                 val startTime = System.currentTimeMillis()

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
@@ -326,6 +327,11 @@ 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}")
         }
@@ -431,6 +437,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) {

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