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

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

@@ -5,6 +5,10 @@ import android.os.Debug
 import android.os.SystemClock
 import android.util.Log
 import android.view.Choreographer
+import android.webkit.WebView
+import io.yourname.androidproject.utils.BridgeUtils
+import io.yourname.androidproject.utils.PerfEventBuffer
+import org.json.JSONObject
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicInteger
 
@@ -13,11 +17,29 @@ import java.util.concurrent.atomic.AtomicInteger
  * Tracks key performance metrics and logs them on app destroy.
  */
 class MetricsMonitor(private val context: Context) {
+
+    // WebView reference for emitting perf events — set via attachWebView()
+    @Volatile private var webView: WebView? = null
+
+    fun attachWebView(wv: WebView) {
+        webView = wv
+    }
+
+    fun detachWebView() {
+        // Flush any open fps-drop episode before losing the WebView reference
+        if (inFpsDropEpisode) emitFpsDropEpisode(endTime = SystemClock.elapsedRealtime())
+        webView = null
+    }
+
+    private fun emitPerf(payload: JSONObject) {
+        webView?.let { BridgeUtils.emitPerfEvent(it, payload) }
+    }
     private val TAG = "MetricsMonitor"
 
     // App Startup metrics
     private var appStartTime: Long = SystemClock.elapsedRealtime()
     private var coldStartDuration: Long = 0
+    private var coldStartCompleted = false
 
     // Page Load metrics
     private val pageLoadTimes = mutableMapOf<String, Long>()
@@ -34,6 +56,15 @@ class MetricsMonitor(private val context: Context) {
     private var avgFps = 0.0
     private var fpsReadings = 0
 
+    // fps-drop episode tracking
+    private var inFpsDropEpisode = false
+    private var episodeStartNativeTime: Long = 0
+    private var episodeMinFps = Double.MAX_VALUE
+    private var episodeFpsSum = 0.0
+    private var episodeSampleCount = 0
+    private val FPS_EPISODE_MAX_MS = 10_000L  // force-close after 10s
+    private var lastStableFps = 60.0          // fps reading just before episode started — used to compute deltaFps
+
     // Memory metrics
     private var initialMemory: Long = getMemoryUsage()
     private var peakMemory: Long = initialMemory
@@ -74,8 +105,18 @@ class MetricsMonitor(private val context: Context) {
     }
 
     fun markAppStartComplete() {
+        if (coldStartCompleted) return
+        coldStartCompleted = true
         coldStartDuration = SystemClock.elapsedRealtime() - appStartTime
         Log.d(TAG, "App cold start completed in: $coldStartDuration ms")
+        // Buffer so it is delivered with the post-load batch flush when JS is ready.
+        // emitPerf (live path) would be a no-op here — JS may not have loaded yet.
+        PerfEventBuffer.add(JSONObject().apply {
+            put("type", "cold-start")
+            put("nativeTime", SystemClock.elapsedRealtime())
+            put("durationMs", coldStartDuration)
+            put("thread", Thread.currentThread().name)
+        })
     }
 
     fun trackPageLoadStart(url: String) {
@@ -144,8 +185,14 @@ class MetricsMonitor(private val context: Context) {
         uiBlockingEvents++
     }
 
-    fun recordLongTask() {
+    fun recordLongTask(durationMs: Long = longTaskThreshold) {
         longTasksDetected++
+        emitPerf(JSONObject().apply {
+            put("type", "long-task")
+            put("nativeTime", SystemClock.elapsedRealtime())
+            put("durationMs", durationMs)
+            put("thread", Thread.currentThread().name)
+        })
     }
 
     private fun startFrameMonitoring() {
@@ -173,27 +220,106 @@ class MetricsMonitor(private val context: Context) {
         val timeSpan = now - lastFpsCheckTime
         lastFpsCheckTime = now
 
-        if (timeSpan > 0) {
-            currentFps = frames * 1000.0 / timeSpan
-
-            // Update min/max/avg
-            if (minFps == Double.MAX_VALUE) minFps = currentFps
-            minFps = minFps.coerceAtMost(currentFps)
-            maxFps = maxFps.coerceAtLeast(currentFps)
-
-            val totalFps = avgFps * fpsReadings + currentFps
-            fpsReadings++
-            avgFps = totalFps / fpsReadings
+        if (timeSpan <= 0) return
+
+        currentFps = frames * 1000.0 / timeSpan
+
+        // Update session-level min/max/avg
+        if (minFps == Double.MAX_VALUE) minFps = currentFps
+        minFps = minFps.coerceAtMost(currentFps)
+        maxFps = maxFps.coerceAtLeast(currentFps)
+        val totalFps = avgFps * fpsReadings + currentFps
+        fpsReadings++
+        avgFps = totalFps / fpsReadings
+
+        if (currentFps < 55.0) {
+            if (!inFpsDropEpisode) {
+                // Start new episode — capture the last stable fps as baseline for deltaFps
+                inFpsDropEpisode = true
+                episodeStartNativeTime = now - timeSpan  // start of the measured window
+                episodeMinFps = currentFps
+                episodeFpsSum = currentFps
+                episodeSampleCount = 1
+                // lastStableFps already holds the previous reading (set in the else branch below)
+            } else {
+                // Accumulate into current episode
+                episodeMinFps = episodeMinFps.coerceAtMost(currentFps)
+                episodeFpsSum += currentFps
+                episodeSampleCount++
+
+                // Force-close if episode has run for >= 10s
+                val episodeDuration = now - episodeStartNativeTime
+                if (episodeDuration >= FPS_EPISODE_MAX_MS) {
+                    emitFpsDropEpisode(endTime = now)
+                    // Immediately start a new episode for the continuing drop
+                    inFpsDropEpisode = true
+                    episodeStartNativeTime = now
+                    episodeMinFps = currentFps
+                    episodeFpsSum = currentFps
+                    episodeSampleCount = 1
+                }
+            }
+        } else {
+            // FPS is good — update lastStableFps and close episode if one was open
+            lastStableFps = currentFps
+            if (inFpsDropEpisode) {
+                emitFpsDropEpisode(endTime = now)
+            }
         }
     }
 
+    private fun emitFpsDropEpisode(endTime: Long) {
+        if (!inFpsDropEpisode) return
+        val durationMs = endTime - episodeStartNativeTime
+        val avgEpisodeFps = if (episodeSampleCount > 0) episodeFpsSum / episodeSampleCount else episodeMinFps
+        // deltaFps = how far FPS fell from the last stable reading before the episode
+        val deltaFps = lastStableFps - episodeMinFps
+        emitPerf(JSONObject().apply {
+            put("type", "fps-drop-episode")
+            put("startNativeTime", episodeStartNativeTime)
+            put("endNativeTime", endTime)
+            put("durationMs", durationMs)
+            put("minFps", episodeMinFps)
+            put("avgFps", avgEpisodeFps)
+            put("deltaFps", deltaFps)     // drop magnitude from last stable fps
+            put("baselineFps", lastStableFps)
+            put("thread", Thread.currentThread().name)
+        })
+        inFpsDropEpisode = false
+        episodeMinFps = Double.MAX_VALUE
+        episodeFpsSum = 0.0
+        episodeSampleCount = 0
+    }
+
     private fun monitorMemoryPeriodically() {
         Thread {
             while (!Thread.interrupted()) {
                 try {
-                    currentMemory = getMemoryUsage()
-                    peakMemory = peakMemory.coerceAtLeast(currentMemory)
-                    Thread.sleep(5000) // Check every 5 seconds
+                    val memInfo = Debug.MemoryInfo()
+                    Debug.getMemoryInfo(memInfo)
+
+                    // PSS breakdown — all values in KB, convert to MB
+                    val jvmMb     = memInfo.dalvikPss  / 1024.0  // Kotlin/Java heap
+                    val webviewMb = memInfo.nativePss  / 1024.0  // V8 + Blink + JNI (WebView proxy)
+                    val otherMb   = memInfo.otherPss   / 1024.0  // graphics buffers, code, stack
+                    val totalMb   = memInfo.totalPss   / 1024.0  // what Android OOM killer sees
+
+                    currentMemory = memInfo.totalPss.toLong()
+                    peakMemory    = peakMemory.coerceAtLeast(currentMemory)
+
+                    val now = SystemClock.elapsedRealtime()
+                    emitPerf(JSONObject().apply {
+                        put("type",         "memory-snapshot")
+                        put("nativeTime",    now)
+                        put("jvmMb",        jvmMb)
+                        put("webviewMb",    webviewMb)
+                        put("otherMb",      otherMb)
+                        put("totalMb",      totalMb)
+                        put("peakMb",       peakMemory / 1024.0)
+                        put("thread",       Thread.currentThread().name)
+                        if (coldStartDuration > 0) put("coldStartMs", coldStartDuration)
+                    })
+                    Thread.sleep(5000)
                 } catch (e: InterruptedException) {
                     break
                 }
@@ -324,7 +450,7 @@ class MetricsMonitor(private val context: Context) {
     }
 
     fun cleanup() {
-        // Remove frame callback
+        if (inFpsDropEpisode) emitFpsDropEpisode(endTime = SystemClock.elapsedRealtime())
         Choreographer.getInstance().removeFrameCallback(frameCallback)
     }
 
@@ -338,4 +464,4 @@ class MetricsMonitor(private val context: Context) {
             }
         }
     }
-}
+}

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

@@ -332,8 +332,11 @@ class NativeBridge(
 
     @JavascriptInterface
     fun openCamera(options: String?) {
+        val callId = "openCamera:${android.os.SystemClock.elapsedRealtime()}"
+        BridgeUtils.bridgeCallReceived(callId, "openCamera")
         BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_CAMERA_ERROR, "open camera") {
             mainActivity.runOnUiThread {
+                BridgeUtils.bridgeCallDispatched(callId)
                 if (CameraUtils.hasCameraPermission(mainActivity)) {
                     launchCamera()
                 } else {
@@ -492,10 +495,13 @@ class NativeBridge(
 
     @JavascriptInterface
     fun getDeviceInfo(options: String?) {
+        val callId = "getDeviceInfo:${android.os.SystemClock.elapsedRealtime()}"
+        BridgeUtils.bridgeCallReceived(callId, "getDeviceInfo")
         BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_DEVICE_INFO_ERROR, "get device info") {
             mainActivity.runOnUiThread {
                 val deviceInfo = DeviceInfoUtils.getDeviceInfo(mainActivity, properties)
                 BridgeUtils.logDebug(TAG, "Device info retrieved: $deviceInfo")
+                BridgeUtils.bridgeCallDispatched(callId)
                 BridgeUtils.notifyWeb(webView, BridgeUtils.WebEvents.ON_DEVICE_INFO_SUCCESS, deviceInfo.toString())
             }
         }

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

@@ -5,7 +5,9 @@ import android.util.Log
 import android.util.LruCache
 import android.webkit.WebResourceResponse
 import io.yourname.androidproject.BuildConfig
+import io.yourname.androidproject.utils.PerfEventBuffer
 import kotlinx.coroutines.*
+import org.json.JSONObject
 import java.io.*
 import java.net.HttpURLConnection
 import java.net.URL
@@ -36,6 +38,24 @@ class WebCacheManager(private val context: Context, private val properties: java
         (Runtime.getRuntime().maxMemory() / 1024 / memoryFraction).toInt()
     )
 
+    private fun emitCachePerfEvent(type: String, url: String, startMs: Long, statusCode: Int? = null) {
+        if (!BuildConfig.DEBUG) return
+        PerfEventBuffer.add(JSONObject().apply {
+            put("type", type)
+            put("url", url)
+            put("nativeStartMs", startMs)
+            put("durationMs", android.os.SystemClock.elapsedRealtime() - startMs)
+            put("resourceType", when {
+                url.endsWith(".js") -> "script"
+                url.endsWith(".css") -> "stylesheet"
+                url.endsWith(".png") || url.endsWith(".jpg") || url.endsWith(".jpeg") || url.endsWith(".svg") -> "image"
+                else -> "other"
+            })
+            put("thread", Thread.currentThread().name)
+            statusCode?.let { put("statusCode", it) }
+        })
+    }
+
     init {
         try {
             cacheDir.mkdirs()
@@ -81,6 +101,7 @@ class WebCacheManager(private val context: Context, private val properties: java
     @Suppress("UNUSED_PARAMETER")
     fun getCachedResponseSync(url: String, headers: Map<String, String>): WebResourceResponse? {
         return try {
+            val startMs = android.os.SystemClock.elapsedRealtime()
             val cacheKey = generateCacheKey(url)
             val currentTime = System.currentTimeMillis()
 
@@ -94,6 +115,7 @@ class WebCacheManager(private val context: Context, private val properties: java
                         Log.d(TAG, "✅ Serving from memory cache (sync): $url")
                         Log.d(FLOW_TAG, "ASSET cache-hit source=memory ageMs=$age url=$url")
                     }
+                    emitCachePerfEvent("cache-hit-memory", url, startMs)
                     return memoryCacheEntry.toResponse()
                 }
                 if (BuildConfig.DEBUG) {
@@ -113,6 +135,7 @@ class WebCacheManager(private val context: Context, private val properties: java
                         Log.d(TAG, "✅ Serving from disk cache (sync): $url")
                         Log.d(FLOW_TAG, "ASSET cache-hit source=disk ageMs=$fileAge bytes=${cacheFile.length()} mime=${metadata.mimeType} encoding=${metadata.encoding} url=$url")
                     }
+                    emitCachePerfEvent("cache-hit-disk", url, startMs)
                     return response
                 }
                 if (BuildConfig.DEBUG) {
@@ -125,6 +148,7 @@ class WebCacheManager(private val context: Context, private val properties: java
                 Log.d(TAG, "❌ No valid cache available (sync): $url")
                 Log.d(FLOW_TAG, "ASSET cache-miss url=$url")
             }
+            emitCachePerfEvent("cache-miss-fetch", url, startMs)
             null
         } catch (e: Exception) {
             Log.e(TAG, "Error in getCachedResponseSync for URL: $url: ${e.message}")
@@ -357,6 +381,7 @@ class WebCacheManager(private val context: Context, private val properties: java
         cacheKey: String
     ): WebResourceResponse? {
         var connection: HttpURLConnection? = null
+        val startMs = android.os.SystemClock.elapsedRealtime()
         try {
             connection = URL(url).openConnection() as HttpURLConnection
             headers.forEach { (key, value) ->
@@ -440,6 +465,7 @@ class WebCacheManager(private val context: Context, private val properties: java
                 if (BuildConfig.DEBUG) {
                     Log.d(FLOW_TAG, "ASSET network-fetch success status=${connection.responseCode} bytes=${responseBytes.size} contentType=$contentType replayMime=$mimeType replayEncoding=$encoding url=$url")
                 }
+                emitCachePerfEvent("network-fetch-complete", url, startMs, connection.responseCode)
                 return response
             }
             if (BuildConfig.DEBUG) {

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

@@ -5,6 +5,8 @@ import android.webkit.WebView
 import io.yourname.androidproject.CatalystConstants
 import org.json.JSONObject
 import android.os.Looper
+import android.os.SystemClock
+import io.yourname.androidproject.BuildConfig
 
 /**
  * Common utilities for native bridge operations
@@ -95,11 +97,64 @@ object BridgeUtils {
         ON_TRANSITION_CANCELLED("ON_TRANSITION_CANCELLED"),
         ON_TRANSITION_TIMEOUT("ON_TRANSITION_TIMEOUT"),
 
+        // Perf telemetry
+        CATALYST_PERF_EVENT("CATALYST_PERF_EVENT"),
     }
     
+    /**
+     * Emit a performance event directly to WebPerfCollector via
+     * window.__catalystPerfEvent(). Bypasses the WebBridge callback system
+     * to keep perf overhead minimal — no JS parsing, no handler lookup.
+     *
+     * Must be called from any thread — posts to main thread automatically.
+     *
+     * @param webView The WebView instance
+     * @param payload JSONObject with at minimum a "type" field
+     */
+    fun emitPerfEvent(webView: WebView, payload: JSONObject) {
+        if (!PerfEventBuffer.isEnabled()) return
+        if (Looper.myLooper() != Looper.getMainLooper()) {
+            // Capture caller thread name before marshalling to main thread
+            if (!payload.has("emitThread")) {
+                payload.put("emitThread", Thread.currentThread().name)
+            }
+            webView.post { emitPerfEvent(webView, payload) }
+            return
+        }
+        try {
+            // Use JSON.parse inside the JS call so we never deal with quote escaping
+            val jsonStr = payload.toString().replace("\\", "\\\\").replace("'", "\\'")
+            webView.evaluateJavascript("window.__catalystPerfEvent && window.__catalystPerfEvent('$jsonStr')", null)
+        } catch (e: Exception) {
+            Log.e(TAG, "emitPerfEvent failed: ${e.message}")
+        }
+    }
+
+    /**
+     * Record that a @JavascriptInterface method was invoked (t0).
+     * Pair with bridgeCallDispatched() at notifyWeb() call site.
+     * No-op in release builds.
+     *
+     * @param callId  Unique identifier for this call (e.g. "getDeviceInfo:<timestamp>")
+     * @param method  Human-readable method name for ApiCollector.js
+     */
+    fun bridgeCallReceived(callId: String, method: String) {
+        if (!BuildConfig.DEBUG) return
+        PerfEventBuffer.bridgeCallReceived(callId, method)
+    }
+
+    /**
+     * Record that native dispatched the callback back to JS (t1).
+     * Must be called just before (or just after) notifyWeb().
+     */
+    fun bridgeCallDispatched(callId: String) {
+        if (!BuildConfig.DEBUG) return
+        PerfEventBuffer.bridgeCallDispatched(callId)
+    }
+
     /**
      * Send a callback to the web layer
-     * 
+     *
      * @param webView The WebView instance
      * @param event The web event to send
      * @param data The data to send (can be null)

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

@@ -2,27 +2,34 @@ package io.yourname.androidproject.utils
 
 import android.app.Activity
 import android.graphics.Rect
+import android.os.SystemClock
 import android.util.TypedValue
 import android.view.View
 import android.view.ViewGroup
 import android.view.ViewTreeObserver
+import android.webkit.WebView
 import androidx.constraintlayout.widget.ConstraintLayout
+import org.json.JSONObject
 
 class KeyboardUtil(
     private val activity: Activity,
-    private val webViewContainer: View
+    private val webViewContainer: View,
+    private val webView: WebView? = null,
 ) {
     private var originalHeight: Int = 0
     private var listener: ViewTreeObserver.OnGlobalLayoutListener? = null
-    
+
     // Keyboard detection threshold in dp - commonly used values are 120-150dp
     private val keyboardThresholdDp = 120f
-    
+
     // Calculate minimum keyboard height in pixels based on device density
     private val keyboardThresholdPx: Int by lazy {
         dpToPx(keyboardThresholdDp)
     }
-    
+
+    // Track keyboard state to avoid spamming events on every layout pass
+    private var keyboardVisible = false
+
     /**
      * Convert density-independent pixels to pixels
      */
@@ -33,7 +40,7 @@ class KeyboardUtil(
             activity.resources.displayMetrics
         ).toInt()
     }
-    
+
     /**
      * Convert pixels to density-independent pixels
      */
@@ -43,7 +50,7 @@ class KeyboardUtil(
 
     fun initialize() {
         val rootView = activity.findViewById<ViewGroup>(android.R.id.content)
-        
+
         webViewContainer.post {
             originalHeight = webViewContainer.height
         }
@@ -53,21 +60,33 @@ class KeyboardUtil(
             val screenHeight = activity.resources.displayMetrics.heightPixels
             val visibleHeight = rect.height()
             val keyboardHeight = screenHeight - visibleHeight
-            
+
             // Use density-independent threshold and consider screen size
             // Also add a minimum percentage of screen height as additional validation
             val minScreenPercentage = (screenHeight * 0.15).toInt() // 15% of screen height
             val effectiveThreshold = maxOf(keyboardThresholdPx, minScreenPercentage)
-            if (keyboardHeight > effectiveThreshold) {
+            val isNowVisible = keyboardHeight > effectiveThreshold
+
+            if (isNowVisible) {
                 // Keyboard visible - resize
                 val params = webViewContainer.layoutParams as ConstraintLayout.LayoutParams
                 params.height = originalHeight - keyboardHeight
                 webViewContainer.layoutParams = params
+
+                if (!keyboardVisible) {
+                    keyboardVisible = true
+                    emitKeyboardEvent("keyboard-show", keyboardHeight)
+                }
             } else {
                 // Keyboard hidden - restore
                 val params = webViewContainer.layoutParams as ConstraintLayout.LayoutParams
                 params.height = originalHeight
                 webViewContainer.layoutParams = params
+
+                if (keyboardVisible) {
+                    keyboardVisible = false
+                    emitKeyboardEvent("keyboard-hide", 0)
+                }
             }
         }
         rootView.viewTreeObserver.addOnGlobalLayoutListener(listener)
@@ -79,4 +98,25 @@ class KeyboardUtil(
             rootView.viewTreeObserver.removeOnGlobalLayoutListener(it)
         }
     }
+
+    // ─── Perf telemetry ──────────────────────────────────────────────────────
+
+    /**
+     * Emit keyboard show/hide event to WebPerfCollector.
+     * Uses SystemClock.elapsedRealtime() so the timestamp is alignable with
+     * native Perfetto traces via window.__NATIVE_TIME_OFFSET.
+     */
+    private fun emitKeyboardEvent(type: String, keyboardHeight: Int) {
+        val wv = webView ?: return
+        try {
+            val payload = JSONObject().apply {
+                put("type", type)
+                put("nativeTime", SystemClock.elapsedRealtime())
+                put("keyboardHeight", keyboardHeight)
+            }
+            BridgeUtils.emitPerfEvent(wv, payload)
+        } catch (e: Exception) {
+            // Non-critical — swallow silently
+        }
+    }
 }

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

@@ -0,0 +1,36 @@
+package io.yourname.androidproject.utils
+
+internal class PerfDeliveryState<T> {
+    data class Batch<T>(val id: String, val payload: T, val generation: Long, val retryCount: Int = 0)
+
+    private var generation = 0L
+    private var sequence = 0L
+    private var inFlight: Batch<T>? = null
+
+    fun hasInFlight(): Boolean = inFlight != null
+
+    fun current(): Batch<T>? = inFlight
+
+    fun begin(payload: T): Batch<T>? {
+        if (inFlight != null) return null
+        return Batch("catalyst-${++sequence}", payload, generation).also { inFlight = it }
+    }
+
+    fun isCurrent(batch: Batch<T>): Boolean = inFlight?.id == batch.id && batch.generation == generation
+
+    fun acknowledge(batch: Batch<T>): Boolean {
+        if (!isCurrent(batch)) return false
+        inFlight = null
+        return true
+    }
+
+    fun retry(batch: Batch<T>, maxRetries: Int): Batch<T>? {
+        if (!isCurrent(batch) || batch.retryCount >= maxRetries) return null
+        return batch.copy(retryCount = batch.retryCount + 1).also { inFlight = it }
+    }
+
+    fun reset() {
+        generation++
+        inFlight = null
+    }
+}