catalyst-core 0.2.0-beta.2 → 0.3.0-beta.1

package/dist/native/iosnativeWebView/Sources/Core/Utils/PerfEventBuffer.swift

@@ -0,0 +1,373 @@
+import Foundation
+import WebKit
+import MachO
+
+enum CatalystPerf {
+    private static let maxBufferSize = 500
+    private static let flushDelayMs: UInt64 = 250
+    private static let flushRetryDelayMs: UInt64 = 250
+    private static let maxFlushRetries = 5
+    private static let periodicFlushIntervalMs: UInt64 = 4_000
+    private static let lock = NSLock()
+
+    private static var buffer: [[String: Any]] = []
+    private static var pendingCalls: [String: (startMs: Int64, method: String)] = [:]
+    private static var flushed = false
+    private static var flushGeneration = 0
+    private static var batchSequence = 0
+    private static var inFlight: PendingBatch?
+    private static weak var periodicWebView: WKWebView?
+    private static var periodicTask: Task<Void, Never>?
+
+    private static var cacheHits = 0
+    private static var cacheMisses = 0
+    private static var cacheFetches = 0
+    private static var cacheTotalMs: Int64 = 0
+    private static var cacheTopSlow: [(durationMs: Int64, filename: String)] = []
+
+    private struct PendingBatch {
+        let id: String
+        let events: [[String: Any]]
+        let generation: Int
+        let retryCount: Int
+    }
+
+    static func nativeTimeMs() -> Int64 {
+        Int64(ProcessInfo.processInfo.systemUptime * 1000)
+    }
+
+    static func add(_ event: [String: Any]) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        var payload = event
+        if payload["nativeTime"] == nil {
+            payload["nativeTime"] = nativeTimeMs()
+        }
+
+        lock.lock()
+        if buffer.count >= maxBufferSize {
+            buffer.removeFirst()
+        }
+        updateCacheSummaryLocked(payload)
+        buffer.append(payload)
+        lock.unlock()
+        #endif
+    }
+
+    static func emit(_ event: [String: Any], to webView: WKWebView?) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        guard let webView else {
+            add(event)
+            return
+        }
+
+        var payload = event
+        if payload["nativeTime"] == nil {
+            payload["nativeTime"] = nativeTimeMs()
+        }
+
+        DispatchQueue.main.async {
+            guard let json = jsonString(payload) else { return }
+            let script = "window.__catalystPerfEvent && window.__catalystPerfEvent(\(javaScriptStringLiteral(json)));"
+            webView.evaluateJavaScript(script)
+        }
+        #endif
+    }
+
+    static func bridgeCallReceived(callId: String, method: String) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        lock.lock()
+        pendingCalls[callId] = (nativeTimeMs(), method)
+        lock.unlock()
+        #endif
+    }
+
+    static func bridgeCallDispatched(callId: String) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        lock.lock()
+        guard let pending = pendingCalls.removeValue(forKey: callId) else {
+            lock.unlock()
+            return
+        }
+        lock.unlock()
+
+        let endMs = nativeTimeMs()
+        add([
+            "type": "api-call",
+            "callId": callId,
+            "method": pending.method,
+            "nativeStartMs": pending.startMs,
+            "nativeEndMs": endMs,
+            "durationMs": endMs - pending.startMs,
+            "thread": Thread.current.name ?? "unknown",
+        ])
+        #endif
+    }
+
+    static func scheduleFlush(_ webView: WKWebView?) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        guard let webView else { return }
+
+        lock.lock()
+        if flushed {
+            lock.unlock()
+            return
+        }
+        flushed = true
+        lock.unlock()
+
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: flushDelayMs * 1_000_000)
+            beginFlush(webView, includeCacheSummary: true)
+            startPeriodicFlush(webView)
+        }
+        #endif
+    }
+
+    static func flushNow(_ webView: WKWebView?) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        guard let webView else { return }
+        Task { @MainActor in
+            beginFlush(webView, includeCacheSummary: false)
+        }
+        #endif
+    }
+
+    static func reset() {
+        #if DEBUG
+        stopPeriodicFlush()
+        lock.lock()
+        buffer.removeAll()
+        flushGeneration += 1
+        inFlight = nil
+        pendingCalls.removeAll()
+        flushed = false
+        cacheHits = 0
+        cacheMisses = 0
+        cacheFetches = 0
+        cacheTotalMs = 0
+        cacheTopSlow.removeAll()
+        lock.unlock()
+        #endif
+    }
+
+    static func memorySnapshot(to webView: WKWebView?, label: String? = nil) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        let currentMb = currentResidentMemoryMb()
+        let event: [String: Any] = [
+            "type": "memory-snapshot",
+            "nativeTime": nativeTimeMs(),
+            "jvmMb": 0,
+            "webviewMb": currentMb,
+            "nativeMb": currentMb,
+            "totalMb": currentMb,
+            "otherMb": 0,
+            "peakMb": currentMb,
+            "thread": Thread.current.name ?? "unknown",
+            "label": label ?? "ios-process",
+        ]
+
+        if let webView {
+            emit(event, to: webView)
+        } else {
+            add(event)
+        }
+        #endif
+    }
+
+    static func injectNativeTimeOffset(into webView: WKWebView?) {
+        #if DEBUG
+        guard ConfigConstants.Profiler.enabled else { return }
+        guard let webView else { return }
+        let nativeNow = nativeTimeMs()
+        DispatchQueue.main.async {
+            webView.evaluateJavaScript("window.__NATIVE_TIME_OFFSET = \(nativeNow) - performance.now();")
+        }
+        #endif
+    }
+
+    private static func startPeriodicFlush(_ webView: WKWebView) {
+        periodicTask?.cancel()
+        periodicWebView = webView
+        periodicTask = Task { @MainActor in
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: periodicFlushIntervalMs * 1_000_000)
+                guard let webView = periodicWebView else { return }
+                lock.lock()
+                let pendingBatch = inFlight
+                lock.unlock()
+                if let pendingBatch {
+                    deliver(pendingBatch, to: webView)
+                } else {
+                    beginFlush(webView, includeCacheSummary: false)
+                }
+                memorySnapshot(to: webView, label: "periodic")
+            }
+        }
+    }
+
+    private static func stopPeriodicFlush() {
+        periodicTask?.cancel()
+        periodicTask = nil
+        periodicWebView = nil
+    }
+
+    @MainActor
+    private static func beginFlush(_ webView: WKWebView, includeCacheSummary: Bool) {
+        lock.lock()
+        guard inFlight == nil else {
+            lock.unlock()
+            return
+        }
+        var events = buffer
+        buffer.removeAll()
+        if includeCacheSummary, let summary = buildCacheSummaryEventLocked() {
+            events.append(summary)
+        }
+        guard !events.isEmpty else {
+            lock.unlock()
+            return
+        }
+        batchSequence += 1
+        let batch = PendingBatch(
+            id: "catalyst-\(batchSequence)",
+            events: events,
+            generation: flushGeneration,
+            retryCount: 0
+        )
+        inFlight = batch
+        lock.unlock()
+
+        deliver(batch, to: webView)
+    }
+
+    @MainActor
+    private static func deliver(_ batch: PendingBatch, to webView: WKWebView) {
+        lock.lock()
+        let isCurrent = inFlight?.id == batch.id && batch.generation == flushGeneration
+        lock.unlock()
+        guard isCurrent, let json = jsonString(batch.events) else { return }
+
+        let script = "window.__catalystPerfBatch ? window.__catalystPerfBatch(\(javaScriptStringLiteral(batch.id)), \(javaScriptStringLiteral(json))) : false"
+        webView.evaluateJavaScript(script) { result, _ in
+            if (result as? Bool) == true {
+                acknowledge(batch)
+            } else {
+                retry(batch, to: webView)
+            }
+        }
+    }
+
+    private static func acknowledge(_ batch: PendingBatch) {
+        lock.lock()
+        if inFlight?.id == batch.id && batch.generation == flushGeneration {
+            inFlight = nil
+        }
+        lock.unlock()
+    }
+
+    private static func retry(_ batch: PendingBatch, to webView: WKWebView) {
+        lock.lock()
+        guard inFlight?.id == batch.id && batch.generation == flushGeneration else {
+            lock.unlock()
+            return
+        }
+        guard batch.retryCount < maxFlushRetries else {
+            lock.unlock()
+            return
+        }
+        let retryBatch = PendingBatch(
+            id: batch.id,
+            events: batch.events,
+            generation: batch.generation,
+            retryCount: batch.retryCount + 1
+        )
+        inFlight = retryBatch
+        lock.unlock()
+
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: flushRetryDelayMs * 1_000_000)
+            deliver(retryBatch, to: webView)
+        }
+    }
+
+    private static func updateCacheSummaryLocked(_ event: [String: Any]) {
+        guard let type = event["type"] as? String else { return }
+        let durationMs = event["durationMs"] as? Int64 ?? Int64(event["durationMs"] as? Int ?? 0)
+        let url = event["url"] as? String ?? ""
+
+        switch type {
+        case "cache-hit-memory", "cache-hit-disk":
+            cacheHits += 1
+        case "cache-miss-fetch":
+            cacheMisses += 1
+        case "network-fetch-complete":
+            cacheFetches += 1
+            cacheTotalMs += durationMs
+            cacheTopSlow.append((durationMs, filename(from: url)))
+            cacheTopSlow = Array(cacheTopSlow.sorted { $0.durationMs > $1.durationMs }.prefix(5))
+        default:
+            break
+        }
+    }
+
+    private static func buildCacheSummaryEventLocked() -> [String: Any]? {
+        let total = cacheHits + cacheMisses
+        guard total > 0 else { return nil }
+        let hitRate = Double(cacheHits) * 100.0 / Double(total)
+        let avgFetchMs = cacheFetches > 0 ? cacheTotalMs / Int64(cacheFetches) : 0
+        return [
+            "type": "cache-summary",
+            "hits": cacheHits,
+            "misses": cacheMisses,
+            "fetches": cacheFetches,
+            "total": total,
+            "hitRatePct": (hitRate * 10).rounded() / 10,
+            "avgFetchMs": avgFetchMs,
+            "topSlowest": cacheTopSlow.map { ["filename": $0.filename, "durationMs": $0.durationMs] },
+            "nativeTime": nativeTimeMs(),
+        ]
+    }
+
+    private static func currentResidentMemoryMb() -> Int {
+        var info = mach_task_basic_info()
+        var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size) / 4
+        let result = withUnsafeMutablePointer(to: &info) {
+            $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
+                task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
+            }
+        }
+        guard result == KERN_SUCCESS else { return 0 }
+        return Int(info.resident_size / 1024 / 1024)
+    }
+
+    private static func filename(from url: String) -> String {
+        URL(string: url)?.lastPathComponent.prefix(40).description ?? String(url.prefix(40))
+    }
+
+    private static func jsonString(_ object: Any) -> String? {
+        guard JSONSerialization.isValidJSONObject(object),
+              let data = try? JSONSerialization.data(withJSONObject: object),
+              let json = String(data: data, encoding: .utf8) else {
+            return nil
+        }
+        return json
+    }
+
+    private static 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/BridgeFileHandler.swift

@@ -48,6 +48,40 @@ class BridgeFileHandler: NSObject {
 
     // MARK: - File Intent Operations
 
+    func exportCatalystTrace(params: Any?) {
+        guard let payload = params as? [String: Any],
+              let filename = payload["filename"] as? String,
+              let trace = payload["trace"] as? String,
+              !filename.isEmpty,
+              !trace.isEmpty else {
+            delegate?.sendErrorCallback(eventName: "ON_INTENT_ERROR", error: "Invalid Catalyst trace export payload", code: "INVALID_PARAMETERS")
+            return
+        }
+
+        let safeFilename = filename.replacingOccurrences(of: "/", with: "-")
+        let exportsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("CatalystTraces", isDirectory: true)
+        let fileURL = exportsURL.appendingPathComponent(safeFilename)
+
+        do {
+            try FileManager.default.createDirectory(at: exportsURL, withIntermediateDirectories: true)
+            try trace.write(to: fileURL, atomically: true, encoding: .utf8)
+            DispatchQueue.main.async { [weak self] in
+                self?.presentSharingSheet(for: fileURL)
+            }
+            delegate?.sendJSONCallback(eventName: "ON_INTENT_SUCCESS", data: [
+                "message": "Catalyst trace exported",
+                "filePath": fileURL.path,
+                "filename": safeFilename,
+                "timestamp": ISO8601DateFormatter().string(from: Date()),
+                "platform": "ios"
+            ])
+        } catch {
+            fileLogger.error("Failed to export Catalyst trace: \(error.localizedDescription)")
+            delegate?.sendErrorCallback(eventName: "ON_INTENT_ERROR", error: "Failed to export Catalyst trace", code: "TRACE_EXPORT_ERROR")
+        }
+    }
+
     // Open file with external app using intent (iOS equivalent of Android intent)
     func openFileWithIntent(params: Any?) {
         fileLogger.debug("openFileWithIntent called with params: \(String(describing: params))")
@@ -337,4 +371,4 @@ extension BridgeFileHandler: UIDocumentInteractionControllerDelegate {
             ])
         }
     }
-}
+}

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

@@ -208,6 +208,15 @@ class BridgeMessageValidator {
             "type": "object",
             "properties": [:],
             "additionalProperties": false
+        ],
+        "exportCatalystTrace": [
+            "type": "object",
+            "properties": [
+                "filename": ["type": "string"],
+                "trace": ["type": "string"]
+            ],
+            "required": ["filename", "trace"],
+            "additionalProperties": false
         ]
     ]
 
@@ -233,34 +242,38 @@ class BridgeMessageValidator {
             )
         }
 
-        // Step 2: Validate message size
-        if let messageData = try? JSONSerialization.data(withJSONObject: message.body, options: []),
-           messageData.count > CatalystConstants.Bridge.maxMessageSize {
-            logger.error("Message size exceeds limit: \(messageData.count) > \(CatalystConstants.Bridge.maxMessageSize)")
+        // Step 2: Validate message body structure
+        guard let body = message.body as? [String: Any] else {
+            logger.error("Invalid message format - body is not a dictionary")
             return BridgeValidationResult(
                 isValid: false,
                 command: nil,
                 params: nil,
                 body: nil,
                 error: BridgeValidationError(
-                    message: "Message too large",
-                    code: "MESSAGE_TOO_LARGE",
+                    message: "Invalid message format",
+                    code: "INVALID_FORMAT",
                     eventName: "BRIDGE_ERROR"
                 )
             )
         }
 
-        // Step 3: Validate message body structure
-        guard let body = message.body as? [String: Any] else {
-            logger.error("Invalid message format - body is not a dictionary")
+        // Step 3: Trace export gets a larger limit only when that debug profiler command is enabled.
+        let rawCommand = body["command"] as? String
+        let maxMessageSize = rawCommand == "exportCatalystTrace" && CatalystConstants.Bridge.isTraceExportEnabled()
+            ? 25 * 1024 * 1024
+            : CatalystConstants.Bridge.maxMessageSize
+        if let messageData = try? JSONSerialization.data(withJSONObject: message.body, options: []),
+           messageData.count > maxMessageSize {
+            logger.error("Message size exceeds limit: \(messageData.count) > \(maxMessageSize)")
             return BridgeValidationResult(
                 isValid: false,
                 command: nil,
                 params: nil,
                 body: nil,
                 error: BridgeValidationError(
-                    message: "Invalid message format",
-                    code: "INVALID_FORMAT",
+                    message: "Message too large",
+                    code: "MESSAGE_TOO_LARGE",
                     eventName: "BRIDGE_ERROR"
                 )
             )

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

@@ -267,7 +267,10 @@ extension NativeBridge: WKScriptMessageHandler {
         logger.debug("Received validated command: \(command)")
 
         // Execute commands with proper error handling
+        let callId = "\(command):\(UUID().uuidString)"
+        CatalystPerf.bridgeCallReceived(callId: callId, method: command)
         executeCommand(command, params: params)
+        CatalystPerf.bridgeCallDispatched(callId: callId)
     }
 
     // MARK: - Command Execution
@@ -295,6 +298,12 @@ extension NativeBridge: WKScriptMessageHandler {
             commandHandler.pickFile(options: optionsString)
         case "openFileWithIntent":
             fileHandler.openFileWithIntent(params: params)
+        case "exportCatalystTrace":
+            guard CatalystConstants.Bridge.isTraceExportEnabled() else {
+                sendErrorCallback(eventName: "BRIDGE_ERROR", error: "Unsupported command: exportCatalystTrace", code: "UNSUPPORTED_COMMAND")
+                return
+            }
+            fileHandler.exportCatalystTrace(params: params)
         case "requestHapticFeedback":
             let feedbackType = delegateHandler.extractFeedbackType(from: params)
             commandHandler.requestHapticFeedback(feedbackType: feedbackType)