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

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

@@ -0,0 +1,44 @@
+import Foundation
+
+// MARK: - VideoStreamState
+//
+// Valid transitions:
+//   IDLE      → STARTING  (start() called)
+//   STARTING  → STREAMING (session running)
+//   STARTING  → IDLE      (permission denied or bind failure)
+//   STREAMING → HOLD      (QR detected)
+//   HOLD      → STREAMING (hold expired)
+//   STREAMING → FLIPPING  (flip() called)
+//   FLIPPING  → STREAMING (rebind complete)
+//   STREAMING → STOPPING  (stop() called)
+//   FLIPPING  → STOPPING  (stop() called mid-flip)
+//   HOLD      → STOPPING  (stop() called during hold)
+//   STOPPING  → IDLE      (session torn down)
+
+enum VideoStreamState {
+    case idle
+    case starting
+    case streaming
+    case hold
+    case flipping
+    case stopping
+
+    func canTransitionTo(_ next: VideoStreamState) -> Bool {
+        switch self {
+        case .idle:      return next == .starting
+        case .starting:  return next == .streaming || next == .idle
+        case .streaming: return next == .hold || next == .flipping || next == .stopping
+        case .hold:      return next == .streaming || next == .stopping
+        case .flipping:  return next == .streaming || next == .stopping
+        case .stopping:  return next == .idle
+        }
+    }
+
+    var isActive: Bool {
+        return self == .streaming || self == .hold || self == .flipping
+    }
+}
+
+protocol VideoStreamStateListener: AnyObject {
+    func onStateChanged(prev: VideoStreamState, next: VideoStreamState)
+}

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

@@ -0,0 +1,60 @@
+import Foundation
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "VideoStreamStateMachine")
+
+private final class WeakListenerBox {
+    weak var value: VideoStreamStateListener?
+    init(_ value: VideoStreamStateListener) { self.value = value }
+}
+
+class VideoStreamStateMachine {
+
+    private var _state: VideoStreamState = .idle
+    private var listeners: [WeakListenerBox] = []
+    private let lock = NSLock()
+
+    var state: VideoStreamState {
+        lock.lock()
+        defer { lock.unlock() }
+        return _state
+    }
+
+    var isActive: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return _state.isActive
+    }
+
+    func addListener(_ listener: VideoStreamStateListener) {
+        lock.lock()
+        listeners.append(WeakListenerBox(listener))
+        lock.unlock()
+    }
+
+    func removeListener(_ listener: VideoStreamStateListener) {
+        lock.lock()
+        listeners.removeAll { $0.value === listener }
+        lock.unlock()
+    }
+
+    @discardableResult
+    func transition(to next: VideoStreamState) -> Bool {
+        lock.lock()
+        let prev = _state
+        guard prev.canTransitionTo(next) else {
+            lock.unlock()
+            logger.warning("Invalid transition: \(String(describing: prev)) → \(String(describing: next)), ignoring")
+            return false
+        }
+        _state = next
+        // Compact nilled-out weak refs and snapshot live listeners under the lock
+        listeners.removeAll { $0.value == nil }
+        let snapshot = listeners.compactMap { $0.value }
+        lock.unlock()
+
+        logger.debug("State: \(String(describing: prev)) → \(String(describing: next))")
+        snapshot.forEach { $0.onStateChanged(prev: prev, next: next) }
+        return true
+    }
+}

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

@@ -0,0 +1,130 @@
+import Foundation
+import AVFoundation
+import UIKit
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "ZoomController")
+
+/// Handles zoom operations:
+///  - setZoom(multiplier:) via bridge — 1.0 = 1x, 2.0 = 2x
+///  - pinch-to-zoom via UIPinchGestureRecognizer
+///
+/// Fires ON_ZOOM_CHANGED via onZoomChanged callback after each zoom change.
+/// Payload: zoomLevel (Float multiplier), minZoom, maxZoom.
+///
+/// Note: iOS has no ML Kit auto-zoom suggestion equivalent.
+/// autoZoom option in start() is accepted but silently ignored on iOS.
+class ZoomController: NSObject {
+
+    private var device: AVCaptureDevice?
+    private let stateMachine: VideoStreamStateMachine
+    private let onZoomChanged: (Float, Float, Float) -> Void  // (zoomLevel, minZoom, maxZoom)
+
+    // Track current zoom so pinch can compute relative delta
+    private var zoomAtPinchStart: CGFloat = 1.0
+    private var isObservingZoom = false
+
+    init(stateMachine: VideoStreamStateMachine,
+         onZoomChanged: @escaping (Float, Float, Float) -> Void) {
+        self.stateMachine = stateMachine
+        self.onZoomChanged = onZoomChanged
+    }
+
+    func attachDevice(_ device: AVCaptureDevice) {
+        if isObservingZoom {
+            self.device?.removeObserver(self, forKeyPath: #keyPath(AVCaptureDevice.videoZoomFactor))
+            isObservingZoom = false
+        }
+        self.device = device
+        device.addObserver(self, forKeyPath: #keyPath(AVCaptureDevice.videoZoomFactor), options: [.new], context: nil)
+        isObservingZoom = true
+    }
+
+    func detachDevice() {
+        if isObservingZoom {
+            device?.removeObserver(self, forKeyPath: #keyPath(AVCaptureDevice.videoZoomFactor))
+            isObservingZoom = false
+        }
+        device = nil
+    }
+
+    deinit {
+        if isObservingZoom {
+            device?.removeObserver(self, forKeyPath: #keyPath(AVCaptureDevice.videoZoomFactor))
+        }
+    }
+
+    override func observeValue(forKeyPath keyPath: String?,
+                               of object: Any?,
+                               change: [NSKeyValueChangeKey: Any]?,
+                               context: UnsafeMutableRawPointer?) {
+        guard keyPath == #keyPath(AVCaptureDevice.videoZoomFactor),
+              let device = object as? AVCaptureDevice else {
+            super.observeValue(forKeyPath: keyPath, of: object, change: change, context: context)
+            return
+        }
+        let current = Float(device.videoZoomFactor)
+        let minZ    = Float(device.minAvailableVideoZoomFactor)
+        let maxZ    = Float(device.maxAvailableVideoZoomFactor)
+        DispatchQueue.main.async { [weak self] in
+            self?.onZoomChanged(current, minZ, maxZ)
+        }
+    }
+
+    // MARK: - Bridge API
+
+    /// Called by NativeBridge setVideoStreamZoom — snaps instantly (no animation ramp).
+    func setZoom(multiplier: Float) {
+        logger.debug("setZoom(\(multiplier)x) called from bridge")
+        applyZoomMultiplier(CGFloat(multiplier), animated: false)
+    }
+
+    /// Apply zoom to the device.
+    /// - animated: false → cancel any in-progress ramp and assign directly (bridge calls).
+    ///             true  → let AVFoundation smooth-ramp (pinch gesture).
+    func applyZoomMultiplier(_ multiplier: CGFloat, animated: Bool = false) {
+        guard let device else {
+            logger.warning("applyZoomMultiplier(\(multiplier)x) — device is nil, skipping")
+            return
+        }
+        let minFactor = device.minAvailableVideoZoomFactor
+        let maxFactor = device.maxAvailableVideoZoomFactor
+        let clamped = multiplier.clamped(to: minFactor...maxFactor)
+        do {
+            try device.lockForConfiguration()
+            if animated {
+                // Smooth ramp for pinch — preserve natural feel.
+                // KVO on videoZoomFactor fires onZoomChanged as the ramp progresses.
+                device.ramp(toVideoZoomFactor: clamped, withRate: 8.0)
+            } else {
+                // Instant snap for bridge calls.
+                // cancelVideoZoomRamp + direct assign triggers one KVO notification.
+                device.cancelVideoZoomRamp()
+                device.videoZoomFactor = clamped
+            }
+            device.unlockForConfiguration()
+            logger.debug("applyZoomMultiplier(\(multiplier)x) → \(clamped)x animated=\(animated)")
+        } catch {
+            logger.error("applyZoomMultiplier failed: \(error.localizedDescription)")
+        }
+    }
+
+    // MARK: - Pinch gesture
+
+    func handlePinchBegan() {
+        zoomAtPinchStart = device?.videoZoomFactor ?? 1.0
+    }
+
+    func handlePinchChanged(scale: CGFloat) {
+        guard stateMachine.isActive else { return }
+        applyZoomMultiplier(zoomAtPinchStart * scale, animated: true)
+    }
+}
+
+// MARK: - Comparable+clamped helper (avoids importing simd)
+
+private extension Comparable {
+    func clamped(to range: ClosedRange<Self>) -> Self {
+        min(max(self, range.lowerBound), range.upperBound)
+    }
+}

package/dist/native/iosnativeWebView/Sources/Core/Constants/CatalystConstants.swift

@@ -73,7 +73,17 @@ public enum CatalystConstants {
                 "getSafeArea",
                 "setScreenSecure",
                 "getScreenSecure",
-                "clearWebData"
+                "clearWebData",
+                "startVideoStream",
+                "stopVideoStream",
+                "flipVideoStream",
+                "sendVideoStreamCommand",
+                "setVideoStreamZoom",
+                "setVideoStreamTorch",
+                "setVideoStreamFps",
+                "startTransition",
+                "commitTransition",
+                "cancelTransition"
             ]
 
             // Check if notifications are enabled via config

package/dist/native/iosnativeWebView/Sources/Core/Plugins/CatalystPlugin.swift

@@ -0,0 +1,5 @@
+import Foundation
+
+public protocol CatalystPlugin {
+    func handle(command: String, data: Any?, bridge: PluginBridgeContext)
+}

package/dist/native/iosnativeWebView/Sources/Core/Plugins/GeneratedPluginIndex.swift

@@ -0,0 +1,6 @@
+import Foundation
+
+enum GeneratedPluginIndex {
+    static let pluginFactories: [String: () -> CatalystPlugin] = [:]
+    static let pluginToCommands: [String: Set<String>] = [:]
+}

package/dist/native/iosnativeWebView/Sources/Core/Plugins/PluginBridge.swift

@@ -0,0 +1,364 @@
+import Foundation
+import WebKit
+import UIKit
+import os
+
+private let pluginBridgeLogger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "PluginBridge")
+
+private struct PluginBridgeValidationError: LocalizedError {
+    let message: String
+    let code: String
+
+    var errorDescription: String? {
+        message
+    }
+}
+
+private struct PluginRequest {
+    let pluginId: String
+    let command: String
+    let data: Any?
+    let requestId: String?
+}
+
+protocol PluginBridgeMessage {
+    var name: String { get }
+    var body: Any { get }
+}
+
+extension WKScriptMessage: PluginBridgeMessage {}
+
+final class PluginBridge: NSObject {
+    private weak var webView: WKWebView?
+    private weak var viewController: UIViewController?
+    private var messageHandlerProxy: WeakScriptMessageHandler?
+    private var isRegistered = false
+
+    private let pluginFactories = GeneratedPluginIndex.pluginFactories
+    private let pluginToCommands = GeneratedPluginIndex.pluginToCommands
+
+    private let bridgeName = "PluginBridge"
+    private let errorEvent = "PLUGIN_BRIDGE_ERROR"
+    private let systemPluginId = "__bridge__"
+
+    init(webView: WKWebView, viewController: UIViewController) {
+        self.webView = webView
+        self.viewController = viewController
+        super.init()
+    }
+
+    func register() {
+        guard !isRegistered else { return }
+        guard let userContentController = webView?.configuration.userContentController else {
+            return
+        }
+        let proxy = WeakScriptMessageHandler(delegate: self)
+        userContentController.add(proxy, name: bridgeName)
+        messageHandlerProxy = proxy
+        isRegistered = true
+    }
+
+    func unregister() {
+        guard isRegistered else { return }
+        webView?.configuration.userContentController.removeScriptMessageHandler(forName: bridgeName)
+        messageHandlerProxy = nil
+        isRegistered = false
+    }
+
+    deinit {
+        unregister()
+    }
+
+    private func parseRequest(_ message: PluginBridgeMessage) throws -> PluginRequest {
+        guard message.name == bridgeName else {
+            throw PluginBridgeValidationError(message: "Invalid message handler", code: "INVALID_PAYLOAD")
+        }
+
+        let body: [String: Any]
+        if let dictionary = message.body as? [String: Any] {
+            body = dictionary
+        } else if let dictionary = message.body as? NSDictionary,
+                  let castedBody = dictionary as? [String: Any] {
+            body = castedBody
+        } else {
+            throw PluginBridgeValidationError(message: "Payload must be an object", code: "INVALID_PAYLOAD")
+        }
+
+        guard JSONSerialization.isValidJSONObject(body) else {
+            throw PluginBridgeValidationError(message: "Payload must be JSON-serializable", code: "INVALID_PAYLOAD")
+        }
+
+        let payloadData: Data
+        do {
+            payloadData = try JSONSerialization.data(withJSONObject: body)
+        } catch {
+            throw PluginBridgeValidationError(message: "Invalid payload", code: "INVALID_PAYLOAD")
+        }
+
+        if payloadData.count > CatalystConstants.Bridge.maxMessageSize {
+            throw PluginBridgeValidationError(message: "Payload exceeds maximum size", code: "INVALID_PAYLOAD")
+        }
+
+        let pluginId = (body["pluginId"] as? String ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let command = (body["command"] as? String ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let requestId = (body["requestId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        return PluginRequest(
+            pluginId: pluginId,
+            command: command,
+            data: body["data"],
+            requestId: requestId?.isEmpty == true ? nil : requestId
+        )
+    }
+
+    private func hasPlugin(_ pluginId: String) -> Bool {
+        pluginFactories[pluginId] != nil
+    }
+
+    private func hasCommand(pluginId: String, command: String) -> Bool {
+        pluginToCommands[pluginId]?.contains(command) ?? false
+    }
+
+    private func sendBridgeError(message: String, code: String, request: PluginRequest?) {
+        let bridge = PluginBridgeContext(
+            webView: webView,
+            viewController: viewController,
+            pluginId: systemPluginId,
+            command: request?.command,
+            requestId: request?.requestId
+        )
+        var payload: [String: Any] = [
+            "message": message,
+            "code": code,
+            "pluginId": request?.pluginId ?? systemPluginId,
+        ]
+        if let command = request?.command, !command.isEmpty {
+            payload["command"] = command
+        }
+        bridge.callback(eventName: errorEvent, data: payload)
+    }
+
+    func handleMessage(_ message: PluginBridgeMessage) {
+        var request: PluginRequest?
+
+        do {
+            let parsedRequest = try parseRequest(message)
+            request = parsedRequest
+
+            if parsedRequest.pluginId.isEmpty {
+                sendBridgeError(message: "pluginId is required", code: "INVALID_PAYLOAD", request: parsedRequest)
+                return
+            }
+            if parsedRequest.command.isEmpty {
+                sendBridgeError(message: "command is required", code: "INVALID_PAYLOAD", request: parsedRequest)
+                return
+            }
+
+            if !hasPlugin(parsedRequest.pluginId) {
+                sendBridgeError(
+                    message: "Unsupported plugin: \(parsedRequest.pluginId)",
+                    code: "PLUGIN_NOT_FOUND",
+                    request: parsedRequest
+                )
+                return
+            }
+
+            if !hasCommand(pluginId: parsedRequest.pluginId, command: parsedRequest.command) {
+                sendBridgeError(
+                    message: "Unsupported command '\(parsedRequest.command)' for plugin '\(parsedRequest.pluginId)'",
+                    code: "COMMAND_NOT_SUPPORTED",
+                    request: parsedRequest
+                )
+                return
+            }
+
+            guard let factory = pluginFactories[parsedRequest.pluginId] else {
+                sendBridgeError(
+                    message: "No plugin registered for id: \(parsedRequest.pluginId)",
+                    code: "PLUGIN_NOT_REGISTERED",
+                    request: parsedRequest
+                )
+                return
+            }
+
+            let plugin = factory()
+            let bridge = PluginBridgeContext(
+                webView: webView,
+                viewController: viewController,
+                pluginId: parsedRequest.pluginId,
+                command: parsedRequest.command,
+                requestId: parsedRequest.requestId
+            )
+            plugin.handle(command: parsedRequest.command, data: parsedRequest.data, bridge: bridge)
+        } catch let error as PluginBridgeValidationError {
+            sendBridgeError(message: error.message, code: error.code, request: request)
+        } catch {
+            pluginBridgeLogger.error("Plugin command failed: \(error.localizedDescription)")
+            sendBridgeError(
+                message: "Plugin execution failed: \(error.localizedDescription)",
+                code: "PLUGIN_EXECUTION_FAILED",
+                request: request
+            )
+        }
+    }
+}
+
+extension PluginBridge: WKScriptMessageHandler {
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        handleMessage(message)
+    }
+}
+
+public final class PluginBridgeContext {
+    public weak var webView: WKWebView?
+    public weak var viewController: UIViewController?
+
+    private let systemPluginId = "__bridge__"
+    private let bridgeErrorEvent = "PLUGIN_BRIDGE_ERROR"
+
+    public let pluginId: String
+    public let command: String?
+    public let requestId: String?
+
+    init(
+        webView: WKWebView?,
+        viewController: UIViewController?,
+        pluginId: String,
+        command: String?,
+        requestId: String?
+    ) {
+        self.webView = webView
+        self.viewController = viewController
+        self.pluginId = pluginId
+        self.command = command
+        self.requestId = requestId
+    }
+
+    public func callback(
+        eventName: String,
+        data: Any?,
+        command: String? = nil
+    ) {
+        let resolvedRequestId = self.requestId
+        let resolvedCommand = command ?? self.command
+        let trimmedEventName = eventName.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedEventName.isEmpty else {
+            emitBridgeError(
+                message: "Rejected callback with blank event name for plugin \(self.pluginId)",
+                code: "INVALID_CALLBACK",
+                requestId: resolvedRequestId,
+                command: resolvedCommand
+            )
+            return
+        }
+        if !dispatchEnvelope(
+            pluginId: pluginId,
+            eventName: trimmedEventName,
+            payload: data,
+            requestId: resolvedRequestId,
+            command: resolvedCommand
+        ) {
+            if pluginId == systemPluginId && trimmedEventName == bridgeErrorEvent {
+                pluginBridgeLogger.error("Failed to dispatch bridge error event for plugin \(self.pluginId)")
+                return
+            }
+
+            emitBridgeError(
+                message: "Failed to dispatch callback \(trimmedEventName) for plugin \(self.pluginId)",
+                code: "PLUGIN_EXECUTION_FAILED",
+                requestId: resolvedRequestId,
+                command: resolvedCommand
+            )
+        }
+    }
+
+    private func emitBridgeError(
+        message: String,
+        code: String,
+        requestId: String?,
+        command: String?
+    ) {
+        var payload: [String: Any] = [
+            "message": message,
+            "code": code,
+            "pluginId": pluginId,
+        ]
+
+        if let command = command, !command.isEmpty {
+            payload["command"] = command
+        }
+
+        if !dispatchEnvelope(
+            pluginId: systemPluginId,
+            eventName: bridgeErrorEvent,
+            payload: payload,
+            requestId: requestId,
+            command: command,
+            logFailures: false
+        ) {
+            pluginBridgeLogger.error("Failed to dispatch bridge error for plugin \(self.pluginId): \(message)")
+        }
+    }
+
+    private func dispatchEnvelope(
+        pluginId: String,
+        eventName: String,
+        payload: Any?,
+        requestId: String?,
+        command: String?,
+        logFailures: Bool = true
+    ) -> Bool {
+        guard let webView = webView else {
+            if logFailures {
+                pluginBridgeLogger.error("WebView unavailable for plugin callback \(eventName)")
+            }
+            return false
+        }
+
+        let envelope: [String: Any] = [
+            "pluginId": pluginId,
+            "eventName": eventName,
+            "payload": payload ?? NSNull(),
+            "requestId": requestId ?? NSNull(),
+            "command": command ?? NSNull(),
+        ]
+
+        guard JSONSerialization.isValidJSONObject(envelope),
+              let envelopeData = try? JSONSerialization.data(withJSONObject: envelope),
+              let envelopeJson = String(data: envelopeData, encoding: .utf8) else {
+            if logFailures {
+                pluginBridgeLogger.error("Failed to serialize plugin callback envelope for \(pluginId).\(eventName)")
+            }
+            return false
+        }
+
+        let envelopeLiteral = javaScriptStringLiteral(envelopeJson)
+        let script = "window.PluginBridgeWeb && window.PluginBridgeWeb.dispatch(\(envelopeLiteral));"
+
+        DispatchQueue.main.async {
+            webView.evaluateJavaScript(
+                script,
+                completionHandler: { _, error in
+                    if let error = error {
+                        pluginBridgeLogger.error(
+                            "Plugin callback JS failed for \(pluginId).\(eventName): \(error.localizedDescription)"
+                        )
+                    }
+                }
+            )
+        }
+
+        return true
+    }
+
+    private func javaScriptStringLiteral(_ value: String) -> String {
+        let escaped = value
+            .replacingOccurrences(of: "\\", with: "\\\\")
+            .replacingOccurrences(of: "\"", with: "\\\"")
+            .replacingOccurrences(of: "\n", with: "\\n")
+            .replacingOccurrences(of: "\r", with: "\\r")
+            .replacingOccurrences(of: "\u{2028}", with: "\\u2028")
+            .replacingOccurrences(of: "\u{2029}", with: "\\u2029")
+        return "\"\(escaped)\""
+    }
+}

package/dist/native/iosnativeWebView/Sources/Core/WebView/BridgeMessageValidator.swift

@@ -370,7 +370,10 @@ class BridgeMessageValidator {
             "cancelLocalNotification",
             "subscribeToTopic",
             "unsubscribeFromTopic",
-            "getSafeArea"
+            "getSafeArea",
+            "startTransition",
+            "commitTransition",
+            "cancelTransition"
         ]
 
         if flexibleCommands.contains(command) {