catalyst-core 0.1.0-beta.3 → 0.1.0-beta.5

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

@@ -0,0 +1,244 @@
+package io.yourname.androidproject.camera
+
+import android.Manifest
+import android.content.pm.PackageManager
+import android.util.Log
+import android.util.Size
+import android.view.View
+import android.hardware.camera2.CaptureRequest
+import android.util.Range
+import androidx.camera.camera2.interop.Camera2Interop
+import androidx.camera.core.Camera
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.core.Preview
+import androidx.camera.core.resolutionselector.ResolutionFilter
+import androidx.camera.core.resolutionselector.ResolutionSelector
+import androidx.camera.core.resolutionselector.ResolutionStrategy
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.camera.view.PreviewView
+import androidx.core.content.ContextCompat
+import androidx.lifecycle.LifecycleOwner
+import io.yourname.androidproject.MainActivity
+import io.yourname.androidproject.utils.BridgeUtils
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+
+/**
+ * Owns the CameraX session lifecycle: bind, stop, flip, setFps.
+ */
+class CameraSessionManager(
+    private val activity: MainActivity,
+    private val previewView: PreviewView,
+    private val stateMachine: VideoStreamStateMachine,
+    private val zoomController: ZoomController,
+    private val torchController: TorchController,
+    private val barcodeDetector: BarcodeDetector,
+    private val onReady: () -> Unit,
+    private val onStopped: () -> Unit,
+    private val onError: (message: String) -> Unit
+) {
+
+    companion object {
+        private const val TAG = "CameraSessionManager"
+        const val PERMISSION_REQUEST_CODE = 1001
+    }
+
+    private var cameraProvider: ProcessCameraProvider? = null
+    private var camera: Camera? = null
+    val cameraExecutor: ExecutorService = Executors.newSingleThreadExecutor()
+
+    private var previewUseCase: Preview? = null
+    private var imageAnalysisUseCase: ImageAnalysis? = null
+
+    // Session params — stored so flip/setFps can rebind with same settings
+    private var currentFacing: String = "back"
+    private var currentFpsMin: Int? = null
+    private var currentFpsMax: Int? = null
+    private var currentScanFormat: String = "all"
+    private var currentAutoZoom: Boolean = false
+    private var currentInitialZoom: Float = 1.0f
+
+    // ---- Public API ----
+
+    fun start(
+        facing: String,
+        autoZoom: Boolean,
+        initialZoomPct: Float,
+        scanFormat: String,
+        fpsMin: Int?,
+        fpsMax: Int?
+    ) {
+        if (cameraProvider != null) {
+            Log.w(TAG, "start() called while already streaming — ignoring")
+            return
+        }
+        currentFacing = facing
+        currentAutoZoom = autoZoom
+        currentInitialZoom = initialZoomPct
+        currentScanFormat = scanFormat
+        currentFpsMin = fpsMin
+        currentFpsMax = fpsMax
+
+        if (ContextCompat.checkSelfPermission(activity, Manifest.permission.CAMERA)
+            == PackageManager.PERMISSION_GRANTED
+        ) {
+            bindCamera()
+        } else {
+            activity.requestPermissions(arrayOf(Manifest.permission.CAMERA), PERMISSION_REQUEST_CODE)
+        }
+    }
+
+    fun stop() {
+        cameraProvider?.unbindAll()
+        cameraProvider = null
+        camera = null
+        previewUseCase = null
+        imageAnalysisUseCase = null
+        barcodeDetector.close()
+        zoomController.detachCamera()
+        torchController.detachCamera()
+        activity.runOnUiThread {
+            previewView.visibility = View.INVISIBLE
+            stateMachine.transition(VideoStreamState.IDLE)
+            onStopped()
+        }
+        Log.d(TAG, "Camera stopped")
+    }
+
+    fun flip() {
+        val newFacing = if (currentFacing == "back") "front" else "back"
+        Log.d(TAG, "flip() — $currentFacing → $newFacing")
+        currentFacing = newFacing
+        cleanupForRebind()
+        bindCamera()
+    }
+
+    fun setFps(min: Int?, max: Int?) {
+        if (min != null && max != null && min > max) {
+            Log.w(TAG, "setFps() — invalid range min=$min > max=$max, ignoring")
+            return
+        }
+        Log.d(TAG, "setFps($min, $max) — restarting session")
+        currentFpsMin = min
+        currentFpsMax = max
+        cleanupForRebind()
+        bindCamera()
+    }
+
+    private fun cleanupForRebind() {
+        barcodeDetector.close()
+        cameraProvider?.unbindAll()
+        camera = null
+        previewUseCase = null
+        imageAnalysisUseCase = null
+        zoomController.detachCamera()
+        torchController.detachCamera()
+    }
+
+    fun onPermissionResult(granted: Boolean) {
+        if (granted) {
+            bindCamera()
+        } else {
+            stateMachine.transition(VideoStreamState.IDLE)
+            onError("Camera permission denied")
+        }
+    }
+
+    fun cleanup() {
+        stop()
+        cameraExecutor.shutdown()
+    }
+
+    // ---- Internal ----
+
+    private fun bindCamera() {
+        val future = ProcessCameraProvider.getInstance(activity)
+        future.addListener({
+            try {
+                cameraProvider = future.get()
+
+                val previewBuilder = Preview.Builder()
+                    .setResolutionSelector(
+                        ResolutionSelector.Builder()
+                            .setResolutionFilter { supportedSizes, _ ->
+                                supportedSizes.sortedByDescending { it.width * it.height }
+                            }
+                            .build()
+                    )
+                val fpsMin = currentFpsMin
+                val fpsMax = currentFpsMax
+                if (fpsMin != null && fpsMax != null) {
+                    if (fpsMin <= fpsMax) {
+                        Camera2Interop.Extender(previewBuilder)
+                            .setCaptureRequestOption(
+                                CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE,
+                                Range(fpsMin, fpsMax)
+                            )
+                    } else {
+                        Log.w(TAG, "bindCamera — invalid FPS range min=$fpsMin > max=$fpsMax, skipping FPS override")
+                    }
+                }
+                previewUseCase = previewBuilder.build().also {
+                    it.setSurfaceProvider { request ->
+                        Log.d(TAG, "Preview resolution negotiated: ${request.resolution.width}x${request.resolution.height}")
+                        previewView.surfaceProvider.onSurfaceRequested(request)
+                    }
+                }
+
+                val resolutionSelector = ResolutionSelector.Builder()
+                    .setResolutionStrategy(
+                        ResolutionStrategy(
+                            Size(1920, 1080),
+                            ResolutionStrategy.FALLBACK_RULE_CLOSEST_HIGHER_THEN_LOWER
+                        )
+                    )
+                    .build()
+
+                imageAnalysisUseCase = barcodeDetector.buildImageAnalysis(
+                    executor = cameraExecutor,
+                    resolutionSelector = resolutionSelector,
+                    autoZoomEnabled = currentAutoZoom,
+                    scanFormat = currentScanFormat
+                )
+
+                cameraProvider?.unbindAll()
+                val boundCamera = cameraProvider?.bindToLifecycle(
+                    activity as LifecycleOwner,
+                    cameraSelector(currentFacing),
+                    previewUseCase!!,
+                    imageAnalysisUseCase!!
+                )
+                if (boundCamera == null) {
+                    Log.e(TAG, "bindToLifecycle returned null — aborting camera start")
+                    stateMachine.transition(VideoStreamState.IDLE)
+                    onError("Failed to bind camera to lifecycle")
+                    return@addListener
+                }
+                camera = boundCamera
+                zoomController.attachCamera(boundCamera)
+                torchController.attachCamera(boundCamera, currentFacing)
+
+                zoomController.applyZoomMultiplier(currentInitialZoom)
+                torchController.notifyReset()
+
+                stateMachine.transition(VideoStreamState.STREAMING)
+
+                activity.runOnUiThread {
+                    previewView.visibility = View.VISIBLE
+                    onReady()
+                }
+                Log.d(TAG, "Camera bound — facing=$currentFacing autoZoom=$currentAutoZoom")
+
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to bind camera", e)
+                stateMachine.transition(VideoStreamState.IDLE)
+                onError("Failed to start camera: ${e.message}")
+            }
+        }, ContextCompat.getMainExecutor(activity))
+    }
+
+    private fun cameraSelector(facing: String) =
+        if (facing == "front") CameraSelector.DEFAULT_FRONT_CAMERA
+        else CameraSelector.DEFAULT_BACK_CAMERA
+}

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

@@ -0,0 +1,70 @@
+package io.yourname.androidproject.camera
+
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Manages the QR hold state — after each detection, results are suppressed for HOLD_DURATION_MS
+ * to prevent the same QR from firing repeatedly and to let auto-zoom relax.
+ *
+ * Uses a suppress flag in BarcodeDetector instead of unbind/rebind — camera pipeline
+ * stays bound the whole time, so there is no flicker.
+ */
+class HoldController(
+    private val stateMachine: VideoStreamStateMachine,
+    private val barcodeDetector: BarcodeDetector
+) {
+
+    private val TAG = "HoldController"
+    private val HOLD_DURATION_MS = 200L
+
+    private val handler = Handler(Looper.getMainLooper())
+    @Volatile private var resumeRunnable: Runnable? = null
+
+    private val lastDetectedValueRef = AtomicReference<String?>(null)
+    val lastDetectedValue: String? get() = lastDetectedValueRef.get()
+
+    /**
+     * Call after a new QR value is confirmed. Suppresses results for HOLD_DURATION_MS,
+     * then re-enables and transitions back to STREAMING.
+     */
+    fun startHold() {
+        if (!stateMachine.transition(VideoStreamState.HOLD)) return
+
+        barcodeDetector.suppressResults = true
+        Log.d(TAG, "Hold started — results suppressed for ${HOLD_DURATION_MS}ms")
+
+        resumeRunnable?.let { handler.removeCallbacks(it) }
+        val runnable = Runnable {
+            if (!stateMachine.state.isActive) return@Runnable
+            barcodeDetector.suppressResults = false
+            stateMachine.transition(VideoStreamState.STREAMING)
+            Log.d(TAG, "Hold ended — results resumed")
+        }
+        resumeRunnable = runnable
+        handler.postDelayed(runnable, HOLD_DURATION_MS)
+    }
+
+    /**
+     * Call on stop() or flip() to cancel any pending hold and clear detection memory.
+     */
+    fun reset() {
+        resumeRunnable?.let { handler.removeCallbacks(it) }
+        resumeRunnable = null
+        barcodeDetector.suppressResults = false
+        lastDetectedValueRef.set(null)
+        Log.d(TAG, "Hold state reset")
+    }
+
+    /**
+     * Returns true if this value is new (not a repeat of the last detected value).
+     * Also updates lastDetectedValue if it is new.
+     */
+    fun isNewValue(value: String): Boolean {
+        // compareAndSet atomically checks-and-updates — eliminates TOCTOU race
+        // between the read and the write on lastDetectedValue.
+        return lastDetectedValueRef.getAndSet(value) != value
+    }
+}

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

@@ -0,0 +1,57 @@
+package io.yourname.androidproject.camera
+
+import android.content.Context
+import android.util.Log
+import androidx.camera.core.Camera
+import androidx.core.content.ContextCompat
+
+/**
+ * Manages torch (flashlight) state.
+ * Guards against front-camera torch calls.
+ * Fires ON_TORCH_CHANGED via [onTorchChanged] callback only after the
+ * hardware operation succeeds (ListenableFuture resolved on main thread).
+ */
+class TorchController(
+    private val context: Context,
+    private val onTorchChanged: (enabled: Boolean) -> Unit
+) {
+
+    private val TAG = "TorchController"
+
+    private var camera: Camera? = null
+    private var currentFacing: String = "back"
+
+    fun attachCamera(cam: Camera, facing: String) {
+        camera = cam
+        currentFacing = facing
+    }
+
+    fun detachCamera() {
+        camera = null
+    }
+
+    fun setTorch(on: Boolean) {
+        val cam = camera ?: run {
+            Log.w(TAG, "setTorch($on) — camera is null, skipping")
+            return
+        }
+        if (currentFacing == "front") {
+            Log.w(TAG, "setTorch($on) — front camera has no torch, ignoring")
+            return
+        }
+        Log.d(TAG, "setTorch($on)")
+        cam.cameraControl.enableTorch(on).addListener(
+            {
+                Log.d(TAG, "enableTorch($on) resolved — notifying")
+                onTorchChanged(on)
+            },
+            ContextCompat.getMainExecutor(context)
+        )
+    }
+
+    /** Called after every bindCamera — torch always resets to off on session start. */
+    fun notifyReset() {
+        onTorchChanged(false)
+        Log.d(TAG, "Torch reset to off (new session)")
+    }
+}

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

@@ -0,0 +1,41 @@
+package io.yourname.androidproject.camera
+
+/**
+ * State machine for the video stream lifecycle.
+ *
+ * Valid transitions:
+ *   IDLE       → STARTING   (start() called, permission check begins)
+ *   STARTING   → STREAMING  (camera bound successfully)
+ *   STARTING   → IDLE       (permission denied or bind failure)
+ *   STREAMING  → HOLD       (QR detected — analyzer unbound for hold duration)
+ *   HOLD       → STREAMING  (hold expired — analyzer rebound)
+ *   STREAMING  → FLIPPING   (flip() called)
+ *   FLIPPING   → STREAMING  (rebind complete after flip)
+ *   STREAMING  → STOPPING   (stop() called)
+ *   FLIPPING   → STOPPING   (stop() called mid-flip)
+ *   HOLD       → STOPPING   (stop() called during hold)
+ *   STOPPING   → IDLE       (unbind complete)
+ */
+enum class VideoStreamState {
+    IDLE,
+    STARTING,
+    STREAMING,
+    HOLD,
+    FLIPPING,
+    STOPPING;
+
+    fun canTransitionTo(next: VideoStreamState): Boolean = when (this) {
+        IDLE      -> next == STARTING
+        STARTING  -> next == STREAMING || next == IDLE
+        STREAMING -> next == HOLD || next == FLIPPING || next == STOPPING
+        HOLD      -> next == STREAMING || next == STOPPING
+        FLIPPING  -> next == STREAMING || next == STOPPING
+        STOPPING  -> next == IDLE
+    }
+
+    val isActive: Boolean get() = this == STREAMING || this == HOLD || this == FLIPPING
+}
+
+interface VideoStreamStateListener {
+    fun onStateChanged(prev: VideoStreamState, next: VideoStreamState)
+}

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

@@ -0,0 +1,40 @@
+package io.yourname.androidproject.camera
+
+import android.util.Log
+import java.util.concurrent.CopyOnWriteArrayList
+
+class VideoStreamStateMachine {
+
+    private val TAG = "VideoStreamStateMachine"
+
+    @Volatile
+    var state: VideoStreamState = VideoStreamState.IDLE
+        private set
+
+    private val listeners = CopyOnWriteArrayList<VideoStreamStateListener>()
+
+    fun addListener(listener: VideoStreamStateListener) {
+        if (!listeners.contains(listener)) listeners.add(listener)
+    }
+
+    fun removeListener(listener: VideoStreamStateListener) {
+        listeners.remove(listener)
+    }
+
+    @Synchronized
+    fun transition(next: VideoStreamState): Boolean {
+        val prev = state
+        if (!prev.canTransitionTo(next)) {
+            Log.w(TAG, "Invalid transition: $prev → $next, ignoring")
+            return false
+        }
+        state = next
+        Log.d(TAG, "State: $prev → $next")
+        // Notify outside the synchronized block to prevent deadlock if a listener
+        // calls back into transition() on the same thread.
+        val snapshot = listeners.toList()
+        return true.also { snapshot.forEach { it.onStateChanged(prev, next) } }
+    }
+
+    val isActive: Boolean get() = state.isActive
+}

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

@@ -0,0 +1,75 @@
+package io.yourname.androidproject.camera
+
+import android.graphics.RectF
+import android.util.Log
+import android.webkit.WebView
+import org.json.JSONObject
+
+/**
+ * Pure coordinate math — converts JS viewfinder rect → screen-absolute rect
+ * and maps ML Kit barcode bounding boxes from image space → screen space.
+ * Uses WebView for origin offset and PreviewView dimensions for scale.
+ */
+object ViewfinderMapper {
+
+    private const val TAG = "ViewfinderMapper"
+
+    /**
+     * Parse viewfinder rect from JS JSON and convert to screen-absolute coordinates.
+     * JS sends coords relative to WebView top-left; we add the WebView's on-screen origin.
+     *
+     * @return Pair(screenAbsoluteRect, jsRelativeRect) or null if parsing fails.
+     */
+    fun parseViewfinderRect(json: JSONObject, webView: WebView): Pair<RectF, RectF>? {
+        return try {
+            val x = json.getDouble("x").toFloat()
+            val y = json.getDouble("y").toFloat()
+            val w = json.getDouble("width").toFloat()
+            val h = json.getDouble("height").toFloat()
+
+            val jsRect = RectF(x, y, x + w, y + h)
+
+            val loc = IntArray(2)
+            webView.getLocationOnScreen(loc)
+            val originX = loc[0].toFloat()
+            val originY = loc[1].toFloat()
+
+            val screenRect = RectF(x + originX, y + originY, x + originX + w, y + originY + h)
+            Log.d(TAG, "viewfinderScreenRect: left=${screenRect.left} top=${screenRect.top} right=${screenRect.right} bottom=${screenRect.bottom}")
+            Pair(screenRect, jsRect)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to parse viewfinderRect: ${e.message}")
+            null
+        }
+    }
+
+    /**
+     * Map a barcode bounding box from ML Kit image space → screen space.
+     *
+     * ML Kit boxes are in post-rotation image space (after imgW/imgH swap).
+     * PreviewView uses FILL_CENTER — compute uniform scale + center offset.
+     */
+    fun mapBarcodeToScreen(
+        boxLeft: Int, boxTop: Int, boxRight: Int, boxBottom: Int,
+        imageWidth: Int, imageHeight: Int,
+        previewWidth: Float, previewHeight: Float
+    ): RectF? {
+        if (previewWidth == 0f || previewHeight == 0f) {
+            Log.w(TAG, "previewView has zero size — cannot map barcode to screen")
+            return null
+        }
+        if (imageWidth == 0 || imageHeight == 0) {
+            Log.w(TAG, "imageWidth/imageHeight is zero — cannot map barcode to screen")
+            return null
+        }
+        val scale = maxOf(previewWidth / imageWidth.toFloat(), previewHeight / imageHeight.toFloat())
+        val offsetX = (previewWidth - imageWidth * scale) / 2f
+        val offsetY = (previewHeight - imageHeight * scale) / 2f
+        return RectF(
+            boxLeft   * scale + offsetX,
+            boxTop    * scale + offsetY,
+            boxRight  * scale + offsetX,
+            boxBottom * scale + offsetY
+        )
+    }
+}

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

@@ -0,0 +1,156 @@
+package io.yourname.androidproject.camera
+
+import android.animation.ValueAnimator
+import android.util.Log
+import android.view.MotionEvent
+import android.view.ScaleGestureDetector
+import android.view.animation.DecelerateInterpolator
+import androidx.camera.core.Camera
+import android.content.Context
+
+/**
+ * Handles all zoom operations:
+ *  - setZoom(multiplier: Float) via bridge — 1.0 = 1x, 2.0 = 2x
+ *  - pinch-to-zoom via ScaleGestureDetector
+ *  - auto-zoom suggestion callback (wired from BarcodeDetector)
+ *
+ * Fires ON_ZOOM_CHANGED via [onZoomChanged] callback after each zoom change.
+ * Payload: zoomLevel (Float multiplier, e.g. 1.5), minZoom, maxZoom.
+ */
+class ZoomController(
+    context: Context,
+    private val stateMachine: VideoStreamStateMachine,
+    private val onZoomChanged: (zoomLevel: Float, minZoom: Float, maxZoom: Float) -> Unit
+) {
+
+    private val TAG = "ZoomController"
+
+    private var camera: Camera? = null
+
+    // Smooth auto-zoom state
+    private var zoomAnimator: ValueAnimator? = null
+    private var lastSuggestedRatio: Float = -1f
+    private var consecutiveSuggestionCount: Int = 0
+    private val SUGGESTION_CONFIRM_FRAMES = 2      // frames before committing to a zoom target
+    private val SUGGESTION_TOLERANCE = 0.1f        // ratio delta considered "same target"
+    private val ZOOM_ANIMATION_DURATION_MS = 300L
+
+    private val scaleGestureDetector = ScaleGestureDetector(
+        context,
+        object : ScaleGestureDetector.SimpleOnScaleGestureListener() {
+            override fun onScale(detector: ScaleGestureDetector): Boolean {
+                if (!stateMachine.isActive) return true
+                val cam = camera ?: return true
+                val zoomState = cam.cameraInfo.zoomState.value ?: return true
+                val newRatio = (zoomState.zoomRatio * detector.scaleFactor)
+                    .coerceIn(zoomState.minZoomRatio, zoomState.maxZoomRatio)
+                cam.cameraControl.setZoomRatio(newRatio)
+                onZoomChanged(newRatio, zoomState.minZoomRatio, zoomState.maxZoomRatio)
+                return true
+            }
+        }
+    )
+
+    fun attachCamera(cam: Camera) {
+        camera = cam
+    }
+
+    fun detachCamera() {
+        cancelZoomAnimation()
+        camera = null
+    }
+
+    fun onTouchEvent(event: MotionEvent): Boolean {
+        return if (stateMachine.isActive) scaleGestureDetector.onTouchEvent(event) else false
+    }
+
+    /** Called from bridge: multiplier e.g. 1.0=1x, 2.0=2x */
+    fun setZoom(multiplier: Float) {
+        Log.d(TAG, "setZoom(${multiplier}x) called")
+        applyZoomMultiplier(multiplier)
+    }
+
+    fun applyZoomMultiplier(multiplier: Float) {
+        val cam = camera ?: run {
+            Log.w(TAG, "applyZoomMultiplier(${multiplier}x) — camera is null, skipping")
+            return
+        }
+        val zoomState = cam.cameraInfo.zoomState.value ?: run {
+            Log.w(TAG, "applyZoomMultiplier(${multiplier}x) — zoomState is null, skipping")
+            return
+        }
+        val min = zoomState.minZoomRatio
+        val max = zoomState.maxZoomRatio
+        val ratio = multiplier.coerceIn(min, max)
+        Log.d(TAG, "applyZoomMultiplier(${multiplier}x) → ratio=$ratio (min=$min max=$max)")
+        cam.cameraControl.setZoomRatio(ratio)
+        onZoomChanged(ratio, min, max)
+    }
+
+    /**
+     * Auto-zoom suggestion from ML Kit ZoomSuggestionOptions.
+     * Zoom-only-up guard: never apply a suggestion that would zoom out.
+     * Debounce: only commit after SUGGESTION_CONFIRM_FRAMES consecutive frames
+     * with the same target (within SUGGESTION_TOLERANCE).
+     * Animation: smoothly interpolates from current ratio to target over ZOOM_ANIMATION_DURATION_MS.
+     */
+    fun onAutoZoomSuggestion(suggestedRatio: Float): Boolean {
+        val cam = camera ?: return false
+        val zoomState = cam.cameraInfo.zoomState.value ?: return false
+        val clamped = suggestedRatio.coerceIn(zoomState.minZoomRatio, zoomState.maxZoomRatio)
+
+        // Zoom-only-up guard
+        if (clamped <= zoomState.zoomRatio) {
+            Log.d(TAG, "auto-zoom suggestion=$suggestedRatio ignored — would zoom out")
+            consecutiveSuggestionCount = 0
+            lastSuggestedRatio = -1f
+            return false
+        }
+
+        // Debounce: count consecutive frames pointing at the same target
+        if (Math.abs(clamped - lastSuggestedRatio) <= SUGGESTION_TOLERANCE) {
+            consecutiveSuggestionCount++
+        } else {
+            consecutiveSuggestionCount = 1
+            lastSuggestedRatio = clamped
+        }
+
+        if (consecutiveSuggestionCount < SUGGESTION_CONFIRM_FRAMES) {
+            Log.d(TAG, "auto-zoom debounce: $consecutiveSuggestionCount/$SUGGESTION_CONFIRM_FRAMES for target=$clamped")
+            return false
+        }
+
+        // Confirmed — reset counters and animate
+        consecutiveSuggestionCount = 0
+        lastSuggestedRatio = -1f
+
+        val fromRatio = zoomState.zoomRatio
+        val minZoom = zoomState.minZoomRatio
+        val maxZoom = zoomState.maxZoomRatio
+        Log.d(TAG, "auto-zoom: animating $fromRatio → $clamped")
+
+        zoomAnimator?.cancel()
+        zoomAnimator = ValueAnimator.ofFloat(fromRatio, clamped).apply {
+            duration = ZOOM_ANIMATION_DURATION_MS
+            interpolator = DecelerateInterpolator()
+            addUpdateListener { animator ->
+                val ratio = animator.animatedValue as Float
+                cam.cameraControl.setZoomRatio(ratio)
+                onZoomChanged(ratio, minZoom, maxZoom)
+            }
+            start()
+        }
+        return true
+    }
+
+    fun cancelZoomAnimation() {
+        zoomAnimator?.cancel()
+        zoomAnimator = null
+        consecutiveSuggestionCount = 0
+        lastSuggestedRatio = -1f
+    }
+
+    fun currentMaxZoomRatio(): Float {
+        return camera?.cameraInfo?.zoomState?.value?.maxZoomRatio ?: 8.0f
+    }
+}

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

@@ -0,0 +1,7 @@
+package io.yourname.androidproject.plugins
+
+import org.json.JSONObject
+
+interface CatalystPlugin {
+    fun handle(command: String, data: JSONObject?, bridge: PluginBridgeContext)
+}