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

package/dist/native/iosnativeWebView/Sources/Core/Camera/CameraPreviewView.swift

@@ -0,0 +1,58 @@
+import SwiftUI
+import UIKit
+import AVFoundation
+
+/// UIViewRepresentable that hosts the camera preview layer.
+/// Placed at ZStack index 0 (behind WebViewContainer).
+/// The preview layer is managed by CameraSessionManager — this view just
+/// provides the UIView container that CameraSessionManager embeds into.
+public struct CameraPreviewView: UIViewRepresentable {
+
+    public let cameraManager: NativeCameraManager
+
+    public init(cameraManager: NativeCameraManager) {
+        self.cameraManager = cameraManager
+    }
+
+    public func makeUIView(context: Context) -> UIView {
+        let view = UIView()
+        view.backgroundColor = .clear
+        cameraManager.setPreviewView(view)
+
+        // Pinch gesture for zoom
+        let pinch = UIPinchGestureRecognizer(target: context.coordinator,
+                                             action: #selector(Coordinator.handlePinch(_:)))
+        view.addGestureRecognizer(pinch)
+        return view
+    }
+
+    public func updateUIView(_ uiView: UIView, context: Context) {
+        // updateUIView is always called on the main thread — update frame directly.
+        uiView.layer.sublayers?
+            .compactMap { $0 as? AVCaptureVideoPreviewLayer }
+            .forEach { $0.frame = uiView.bounds }
+    }
+
+    public func makeCoordinator() -> Coordinator {
+        Coordinator(cameraManager: cameraManager)
+    }
+
+    public class Coordinator: NSObject {
+        private let cameraManager: NativeCameraManager
+
+        public init(cameraManager: NativeCameraManager) {
+            self.cameraManager = cameraManager
+        }
+
+        @objc func handlePinch(_ recognizer: UIPinchGestureRecognizer) {
+            switch recognizer.state {
+            case .began:
+                cameraManager.handlePinchBegan()
+            case .changed:
+                cameraManager.handlePinchChanged(scale: recognizer.scale)
+            default:
+                break
+            }
+        }
+    }
+}

package/dist/native/iosnativeWebView/Sources/Core/Camera/CameraSessionManager.swift

@@ -0,0 +1,308 @@
+import Foundation
+import AVFoundation
+import UIKit
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "CameraSessionManager")
+
+/// Owns the AVCaptureSession lifecycle: configure, start, stop, flip, setFps.
+/// Mirrors Android's CameraSessionManager.kt — same public API shape.
+class CameraSessionManager: NSObject {
+
+    private let stateMachine: VideoStreamStateMachine
+    private let zoomController: ZoomController
+    private let torchController: TorchController
+    private let barcodeDetector: BarcodeDetector
+    private let onReady: () -> Void
+    private let onStopped: () -> Void
+    private let onError: (String) -> Void
+
+    private var session: AVCaptureSession?
+    private var previewLayer: AVCaptureVideoPreviewLayer?
+    private weak var previewView: UIView?
+    private let sessionQueue = DispatchQueue(label: "com.catalyst.camera.session")
+
+    // Session params — stored so flip/setFps can rebind with same settings.
+    // paramsLock guards reads/writes since callers may be on any thread while
+    // sessionQueue reads them concurrently.
+    private let paramsLock = NSLock()
+    private var _currentFacing: String = "back"
+    private var _currentFpsMin: Int?
+    private var _currentFpsMax: Int?
+    private var _currentScanFormat: String = "all"
+    private var _currentInitialZoom: Float = 1.0
+
+    private var currentFacing: String {
+        get { paramsLock.lock(); defer { paramsLock.unlock() }; return _currentFacing }
+        set { paramsLock.lock(); _currentFacing = newValue; paramsLock.unlock() }
+    }
+    private var currentFpsMin: Int? {
+        get { paramsLock.lock(); defer { paramsLock.unlock() }; return _currentFpsMin }
+        set { paramsLock.lock(); _currentFpsMin = newValue; paramsLock.unlock() }
+    }
+    private var currentFpsMax: Int? {
+        get { paramsLock.lock(); defer { paramsLock.unlock() }; return _currentFpsMax }
+        set { paramsLock.lock(); _currentFpsMax = newValue; paramsLock.unlock() }
+    }
+    private var currentScanFormat: String {
+        get { paramsLock.lock(); defer { paramsLock.unlock() }; return _currentScanFormat }
+        set { paramsLock.lock(); _currentScanFormat = newValue; paramsLock.unlock() }
+    }
+    private var currentInitialZoom: Float {
+        get { paramsLock.lock(); defer { paramsLock.unlock() }; return _currentInitialZoom }
+        set { paramsLock.lock(); _currentInitialZoom = newValue; paramsLock.unlock() }
+    }
+
+    init(stateMachine: VideoStreamStateMachine,
+         zoomController: ZoomController,
+         torchController: TorchController,
+         barcodeDetector: BarcodeDetector,
+         onReady: @escaping () -> Void,
+         onStopped: @escaping () -> Void,
+         onError: @escaping (String) -> Void) {
+        self.stateMachine = stateMachine
+        self.zoomController = zoomController
+        self.torchController = torchController
+        self.barcodeDetector = barcodeDetector
+        self.onReady = onReady
+        self.onStopped = onStopped
+        self.onError = onError
+    }
+
+    // MARK: - Public API
+
+    func setPreviewView(_ view: UIView) {
+        previewView = view
+    }
+
+    func start(facing: String,
+               initialZoom: Float,
+               scanFormat: String,
+               fpsMin: Int?,
+               fpsMax: Int?) {
+        currentFacing = facing
+        currentInitialZoom = initialZoom
+        currentScanFormat = scanFormat
+        currentFpsMin = fpsMin
+        currentFpsMax = fpsMax
+
+        checkPermissionAndBind()
+    }
+
+    func stop() {
+        sessionQueue.async { [weak self] in
+            self?.tearDownSession()
+        }
+    }
+
+    func flip() {
+        currentFacing = (currentFacing == "back") ? "front" : "back"
+        logger.debug("flip() → \(self.currentFacing)")
+        sessionQueue.async { [weak self] in
+            self?.rebindSession()
+        }
+    }
+
+    func setFps(min: Int?, max: Int?) {
+        logger.debug("setFps(\(String(describing: min)), \(String(describing: max))) — applying live or rebind")
+        currentFpsMin = min
+        currentFpsMax = max
+        sessionQueue.async { [weak self] in
+            self?.applyFpsToLiveDevice()
+        }
+    }
+
+    func cleanup() {
+        sessionQueue.async { [weak self] in
+            self?.tearDownSession()
+        }
+    }
+
+    // MARK: - Permission
+
+    private func checkPermissionAndBind() {
+        switch AVCaptureDevice.authorizationStatus(for: .video) {
+        case .authorized:
+            sessionQueue.async { [weak self] in self?.bindSession() }
+        case .notDetermined:
+            AVCaptureDevice.requestAccess(for: .video) { [weak self] granted in
+                if granted {
+                    self?.sessionQueue.async { self?.bindSession() }
+                } else {
+                    self?.stateMachine.transition(to: .idle)
+                    self?.onError("Camera permission denied")
+                }
+            }
+        default:
+            stateMachine.transition(to: .idle)
+            onError("Camera permission denied")
+        }
+    }
+
+    // MARK: - Session lifecycle
+
+    private func bindSession() {
+        let newSession = AVCaptureSession()
+        newSession.beginConfiguration()
+        newSession.sessionPreset = .hd1920x1080
+
+        // Input
+        let position: AVCaptureDevice.Position = (currentFacing == "front") ? .front : .back
+        guard let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: position),
+              let input = try? AVCaptureDeviceInput(device: device) else {
+            stateMachine.transition(to: .idle)
+            onError("Failed to open camera device")
+            return
+        }
+        guard newSession.canAddInput(input) else {
+            stateMachine.transition(to: .idle)
+            onError("Cannot add camera input")
+            return
+        }
+        newSession.addInput(input)
+
+        // FPS
+        configureFPS(device: device, fpsMin: currentFpsMin, fpsMax: currentFpsMax)
+
+        // Preview layer — must be created before addOutput so transforms are correct
+        let layer = AVCaptureVideoPreviewLayer(session: newSession)
+        layer.videoGravity = .resizeAspectFill
+
+        newSession.commitConfiguration()
+
+        // Attach barcode detector (adds AVCaptureMetadataOutput to session)
+        barcodeDetector.attach(to: newSession, previewLayer: layer, scanFormat: currentScanFormat)
+
+        // Controllers
+        zoomController.attachDevice(device)
+        torchController.attachDevice(device, facing: currentFacing)
+
+        // Apply initial zoom before starting
+        zoomController.applyZoomMultiplier(CGFloat(currentInitialZoom))
+        torchController.notifyReset()
+
+        self.session = newSession
+        self.previewLayer = layer
+
+        newSession.startRunning()
+
+        // Embed preview layer and fire onReady on main thread.
+        // Preview layer insertion is best-effort — previewView is a weak ref to a
+        // SwiftUI-managed UIView that should always be ready by the time JS calls start(),
+        // but we don't gate onReady() on it. Matches Android: onReady fires as soon as
+        // the camera is bound, regardless of the preview container state.
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            if let view = self.previewView {
+                layer.frame = view.bounds
+                view.layer.insertSublayer(layer, at: 0)
+            }
+            self.stateMachine.transition(to: .streaming)
+            self.onReady()
+            logger.debug("Session started — facing=\(self.currentFacing)")
+        }
+    }
+
+    private func tearDownSession() {
+        guard let session else { return }
+        session.stopRunning()
+        barcodeDetector.detach(from: session)
+        zoomController.detachDevice()
+        torchController.detachDevice()
+        self.session = nil
+
+        DispatchQueue.main.async { [weak self] in
+            self?.previewLayer?.removeFromSuperlayer()
+            self?.previewLayer = nil
+            self?.stateMachine.transition(to: .idle)
+            self?.onStopped()
+        }
+        logger.debug("Session torn down")
+    }
+
+    private func rebindSession() {
+        guard let session else { return }
+        session.stopRunning()
+        barcodeDetector.detach(from: session)
+        zoomController.detachDevice()
+        torchController.detachDevice()
+        self.session = nil
+        let oldPreview = self.previewLayer
+        self.previewLayer = nil
+        DispatchQueue.main.async {
+            oldPreview?.removeFromSuperlayer()
+        }
+        bindSession()
+    }
+
+    /// Apply FPS change to the live device without stopping/restarting the session.
+    /// Eliminates the screen blank that rebindSession() causes.
+    /// Falls back to rebindSession() if no active session exists yet.
+    private func applyFpsToLiveDevice() {
+        guard let session,
+              let input = session.inputs.first as? AVCaptureDeviceInput else {
+            logger.warning("applyFpsToLiveDevice — no active session or input, skipping (stream not yet started)")
+            return
+        }
+        let device = input.device
+        guard let fpsMin = currentFpsMin, let fpsMax = currentFpsMax else {
+            logger.debug("applyFpsToLiveDevice — no FPS values set, skipping")
+            return
+        }
+
+        let targetMin = CMTime(value: 1, timescale: CMTimeScale(fpsMin))
+        let targetMax = CMTime(value: 1, timescale: CMTimeScale(fpsMax))
+
+        let supported = device.activeFormat.videoSupportedFrameRateRanges.first { range in
+            range.minFrameDuration <= targetMin && range.maxFrameDuration >= targetMax
+        }
+        guard supported != nil else {
+            logger.warning("applyFpsToLiveDevice — FPS \(fpsMin)-\(fpsMax) unsupported by current format, falling back to rebind")
+            rebindSession()
+            return
+        }
+
+        // Wrap in beginConfiguration/commitConfiguration to prevent AVCaptureSession
+        // from triggering an internal _buildAndRunGraph (which causes a screen blank).
+        // lockForConfiguration must be called inside the begin/commit pair.
+        session.beginConfiguration()
+        do {
+            try device.lockForConfiguration()
+            device.activeVideoMinFrameDuration = targetMax  // fastest rate = 1/maxFps
+            device.activeVideoMaxFrameDuration = targetMin  // slowest rate = 1/minFps
+            device.unlockForConfiguration()
+        } catch {
+            session.commitConfiguration()
+            logger.error("applyFpsToLiveDevice — lockForConfiguration failed: \(error.localizedDescription), falling back to rebind")
+            rebindSession()
+            return
+        }
+        session.commitConfiguration()
+        logger.debug("applyFpsToLiveDevice — FPS set to \(fpsMin)-\(fpsMax) without session rebind")
+    }
+
+    // MARK: - FPS configuration
+
+    private func configureFPS(device: AVCaptureDevice, fpsMin: Int?, fpsMax: Int?) {
+        guard let fpsMin, let fpsMax else { return }
+        let targetMin = CMTime(value: 1, timescale: CMTimeScale(fpsMin))
+        let targetMax = CMTime(value: 1, timescale: CMTimeScale(fpsMax))
+
+        let supported = device.activeFormat.videoSupportedFrameRateRanges.first { range in
+            range.minFrameDuration <= targetMin && range.maxFrameDuration >= targetMax
+        }
+        guard supported != nil else {
+            logger.warning("FPS range \(fpsMin)-\(fpsMax) not supported by device format, ignoring")
+            return
+        }
+        do {
+            try device.lockForConfiguration()
+            device.activeVideoMinFrameDuration = targetMax  // fastest rate = 1/maxFps
+            device.activeVideoMaxFrameDuration = targetMin  // slowest rate = 1/minFps
+            device.unlockForConfiguration()
+            logger.debug("FPS set to \(fpsMin)-\(fpsMax)")
+        } catch {
+            logger.error("Failed to set FPS: \(error.localizedDescription)")
+        }
+    }
+}

package/dist/native/iosnativeWebView/Sources/Core/Camera/HoldController.swift

@@ -0,0 +1,63 @@
+import Foundation
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "HoldController")
+
+/// Manages QR hold state — after each detection, results are suppressed for HOLD_DURATION
+/// to prevent the same QR from firing repeatedly.
+/// Uses a suppressResults flag on BarcodeDetector instead of stopping the session,
+/// so the camera pipeline stays live and there is no flicker.
+class HoldController {
+
+    private let holdDuration: TimeInterval = 0.2  // 200ms, matches Android
+
+    private let stateMachine: VideoStreamStateMachine
+    private let barcodeDetector: BarcodeDetector
+    private var holdWorkItem: DispatchWorkItem?
+    private let serialQueue = DispatchQueue(label: "com.catalyst.camera.hold")
+
+    private(set) var lastDetectedValue: String?
+
+    init(stateMachine: VideoStreamStateMachine, barcodeDetector: BarcodeDetector) {
+        self.stateMachine = stateMachine
+        self.barcodeDetector = barcodeDetector
+    }
+
+    /// Call after a new QR value is confirmed.
+    func startHold() {
+        guard stateMachine.transition(to: .hold) else { return }
+
+        barcodeDetector.suppressResults = true
+        logger.debug("Hold started — results suppressed for \(self.holdDuration * 1000, format: .fixed(precision: 0))ms")
+
+        let workItem = DispatchWorkItem { [weak self] in
+            guard let self, self.stateMachine.isActive else { return }
+            self.barcodeDetector.suppressResults = false
+            self.stateMachine.transition(to: .streaming)
+            logger.debug("Hold ended — results resumed")
+        }
+        holdWorkItem = workItem
+        serialQueue.asyncAfter(deadline: .now() + holdDuration, execute: workItem)
+    }
+
+    /// Call on stop() or flip() to cancel any pending hold and clear detection memory.
+    func reset() {
+        serialQueue.async { [weak self] in
+            guard let self else { return }
+            self.holdWorkItem?.cancel()
+            self.holdWorkItem = nil
+            self.barcodeDetector.suppressResults = false
+            self.lastDetectedValue = nil
+            logger.debug("Hold state reset")
+        }
+    }
+
+    /// Returns true if this value is new (not a repeat of the last detected value).
+    func isNewValue(_ value: String) -> Bool {
+        serialQueue.sync {
+            if value == lastDetectedValue { return false }
+            lastDetectedValue = value
+            return true
+        }
+    }
+}

package/dist/native/iosnativeWebView/Sources/Core/Camera/NativeCameraManager.swift

@@ -0,0 +1,194 @@
+import Foundation
+import AVFoundation
+import UIKit
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "NativeCameraManager")
+
+/// Mutable reference wrapper so all sub-controller closures share the same callback
+/// even after rewireEvents()/rewireError() replace it post-construction.
+/// NSLock guards concurrent handler replacement vs. invocation.
+private final class EventBox {
+    private let lock = NSLock()
+    private var _handler: (String, [String: Any]?) -> Void
+    init(_ h: @escaping (String, [String: Any]?) -> Void) { _handler = h }
+
+    func call(_ event: String, _ payload: [String: Any]?) {
+        lock.lock()
+        let h = _handler
+        lock.unlock()
+        h(event, payload)
+    }
+
+    func replace(_ h: @escaping (String, [String: Any]?) -> Void) {
+        lock.lock()
+        _handler = h
+        lock.unlock()
+    }
+}
+private final class ErrorBox {
+    private let lock = NSLock()
+    private var _handler: (String) -> Void
+    init(_ h: @escaping (String) -> Void) { _handler = h }
+
+    func call(_ msg: String) {
+        lock.lock()
+        let h = _handler
+        lock.unlock()
+        h(msg)
+    }
+
+    func replace(_ h: @escaping (String) -> Void) {
+        lock.lock()
+        _handler = h
+        lock.unlock()
+    }
+}
+
+/// Thin facade — wires all camera sub-components and exposes the public API
+/// that NativeBridge.swift calls. Mirrors Android's NativeCameraManager.kt.
+public class NativeCameraManager: ObservableObject {
+
+    private let stateMachine: VideoStreamStateMachine
+    private let zoomController: ZoomController
+    private let torchController: TorchController
+    private let barcodeDetector: BarcodeDetector
+    private let sessionManager: CameraSessionManager
+    private let holdController: HoldController
+
+    // Boxes — all sub-controller closures close over these references,
+    // so updating .handler here propagates to all of them immediately.
+    private let eventBox: EventBox
+    private let errorBox: ErrorBox
+
+    public init(onEvent: @escaping (String, [String: Any]?) -> Void,
+                onError: @escaping (String) -> Void) {
+        let eBox = EventBox(onEvent)
+        let errBox = ErrorBox(onError)
+        self.eventBox = eBox
+        self.errorBox = errBox
+
+        let sm = VideoStreamStateMachine()
+        self.stateMachine = sm
+
+        zoomController = ZoomController(
+            stateMachine: sm,
+            onZoomChanged: { zoomLevel, minZoom, maxZoom in
+                let payload: [String: Any] = [
+                    "zoomLevel": round(Double(zoomLevel) * 10) / 10,
+                    "minZoom":   round(Double(minZoom)   * 10) / 10,
+                    "maxZoom":   round(Double(maxZoom)   * 10) / 10
+                ]
+                eBox.call("ON_ZOOM_CHANGED", payload)
+            }
+        )
+
+        torchController = TorchController(
+            onTorchChanged: { enabled in
+                eBox.call("ON_TORCH_CHANGED", ["enabled": enabled])
+            }
+        )
+
+        barcodeDetector = BarcodeDetector()
+
+        sessionManager = CameraSessionManager(
+            stateMachine: sm,
+            zoomController: zoomController,
+            torchController: torchController,
+            barcodeDetector: barcodeDetector,
+            onReady:   { eBox.call("ON_VIDEO_STREAM_READY",   nil) },
+            onStopped: { eBox.call("ON_VIDEO_STREAM_STOPPED", nil) },
+            onError:   { msg in errBox.call(msg) }
+        )
+
+        holdController = HoldController(stateMachine: sm, barcodeDetector: barcodeDetector)
+
+        // Wire detection handler now that holdController exists
+        barcodeDetector.detectionHandler = { [weak holdController, weak sm] value, type, bounds in
+            guard sm?.state != .hold else { return }
+            guard let hc = holdController else { return }
+            if hc.isNewValue(value) {
+                let payload: [String: Any] = ["value": value, "format": BarcodeDetector.formatName(type)]
+                eBox.call("ON_QR_DETECTED", payload)
+                logger.debug("QR detected (new): \(value)")
+            }
+            hc.startHold()
+        }
+    }
+
+    // MARK: - Public API
+
+    public func setPreviewView(_ view: UIView) {
+        sessionManager.setPreviewView(view)
+    }
+
+    public func start(facing: String = "back",
+                      autoZoom: Bool = false,         // accepted, silently ignored on iOS
+                      initialZoom: Float = 1.0,
+                      scanFormat: String = "all",
+                      fpsMin: Int? = nil,
+                      fpsMax: Int? = nil) {
+        guard !stateMachine.isActive else { return }
+        stateMachine.transition(to: .starting)
+        sessionManager.start(
+            facing: facing,
+            initialZoom: initialZoom,
+            scanFormat: scanFormat,
+            fpsMin: fpsMin,
+            fpsMax: fpsMax
+        )
+    }
+
+    public func stop() {
+        guard stateMachine.isActive else { return }
+        holdController.reset()
+        stateMachine.transition(to: .stopping)
+        sessionManager.stop()
+    }
+
+    public func flip() {
+        guard stateMachine.isActive else { return }
+        holdController.reset()
+        stateMachine.transition(to: .flipping)
+        sessionManager.flip()
+    }
+
+    public func setZoom(multiplier: Float) {
+        zoomController.setZoom(multiplier: multiplier)
+    }
+
+    public func setTorch(_ on: Bool) {
+        torchController.setTorch(on)
+    }
+
+    public func setFps(min: Int?, max: Int?) {
+        guard stateMachine.isActive else { return }
+        sessionManager.setFps(min: min, max: max)
+    }
+
+    public func handlePinchBegan() {
+        zoomController.handlePinchBegan()
+    }
+
+    public func handlePinchChanged(scale: CGFloat) {
+        zoomController.handlePinchChanged(scale: scale)
+    }
+
+    public func cleanup() {
+        sessionManager.cleanup()
+    }
+
+    /// Replace the event callback post-construction (called by NativeBridge after init).
+    /// Updates the shared EventBox so all sub-controller closures see the new handler.
+    public func rewireEvents(_ handler: @escaping (String, [String: Any]?) -> Void) {
+        eventBox.replace(handler)
+    }
+
+    /// Replace the error callback post-construction (called by NativeBridge after init).
+    /// Updates the shared ErrorBox so all sub-controller closures see the new handler.
+    public func rewireError(_ handler: @escaping (String) -> Void) {
+        errorBox.replace(handler)
+    }
+
+    public var isStreaming: Bool { stateMachine.isActive }
+}

package/dist/native/iosnativeWebView/Sources/Core/Camera/TorchController.swift

@@ -0,0 +1,60 @@
+import Foundation
+import AVFoundation
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "TorchController")
+
+/// Manages torch (flashlight) state.
+/// Guards against front-camera torch calls.
+/// Fires ON_TORCH_CHANGED via onTorchChanged callback.
+class TorchController {
+
+    private var device: AVCaptureDevice?
+    private var currentFacing: String = "back"
+    private let onTorchChanged: (Bool) -> Void
+
+    init(onTorchChanged: @escaping (Bool) -> Void) {
+        self.onTorchChanged = onTorchChanged
+    }
+
+    func attachDevice(_ device: AVCaptureDevice, facing: String) {
+        self.device = device
+        self.currentFacing = facing
+    }
+
+    func detachDevice() {
+        device = nil
+    }
+
+    func setTorch(_ on: Bool) {
+        guard let device else {
+            logger.warning("setTorch(\(on)) — device is nil, skipping")
+            return
+        }
+        guard currentFacing == "back" else {
+            logger.warning("setTorch(\(on)) — front camera has no torch, ignoring")
+            return
+        }
+        guard device.hasTorch else {
+            logger.warning("setTorch(\(on)) — device has no torch")
+            return
+        }
+
+        do {
+            try device.lockForConfiguration()
+            device.torchMode = on ? .on : .off
+            device.unlockForConfiguration()
+            onTorchChanged(on)
+            logger.debug("setTorch(\(on))")
+        } catch {
+            logger.error("setTorch(\(on)) failed: \(error.localizedDescription)")
+            onTorchChanged(false)
+        }
+    }
+
+    /// Called after every session bind — torch always resets to off on session start.
+    func notifyReset() {
+        onTorchChanged(false)
+        logger.debug("Torch reset to off (new session)")
+    }
+}