@onekeyfe/react-native-perf-stats 3.0.26 → 3.0.28

package/README.md

@@ -1,9 +1,10 @@
 # @onekeyfe/react-native-perf-stats
 
-Native CPU and RAM sampler for React Native, with an optional draggable on-screen overlay. Built on [Nitro Modules](https://nitro.margelo.com/) — the sampler runs on a dedicated background thread so the overlay keeps updating even when the JS thread is frozen.
+Native CPU, RAM, UI-FPS and JS-FPS sampler for React Native, with an optional draggable on-screen overlay. Built on [Nitro Modules](https://nitro.margelo.com/) — the sampler runs on a dedicated background thread so the overlay keeps updating even when the JS thread is frozen.
 
-- **Android**: HandlerThread + `/proc/self/stat` (CPU ticks) + `/proc/self/statm` (RSS); overlay attached via `WindowManager` to the current Activity (no `SYSTEM_ALERT_WINDOW` permission).
-- **iOS**: GCD dispatch source + `task_info` (`phys_footprint`); overlay added as a `UILabel` on the key `UIWindow`.
+- **Android**: HandlerThread + `/proc/self/stat` (CPU ticks) + `/proc/self/statm` (RSS) + `Choreographer.FrameCallback` (UI FPS); overlay attached via `WindowManager` to the current Activity (no `SYSTEM_ALERT_WINDOW` permission).
+- **iOS**: GCD dispatch source + `task_info` (`phys_footprint`) + `CADisplayLink` (UI FPS); overlay added as a `UILabel` on the key `UIWindow`.
+- **JS FPS**: opt-in JS-side `requestAnimationFrame` ticker that pushes its per-second count to native via `setJsFpsHint`. Started by `startJsFpsTracker()`.
 
 ## Installation
 
@@ -19,6 +20,7 @@ yarn add @onekeyfe/react-native-perf-stats react-native-nitro-modules
 import { ReactNativePerfStats } from '@onekeyfe/react-native-perf-stats';
 
 // Start sampling at 1 Hz. Idempotent — calling again just updates the interval.
+// Also kicks off the JS-side rAF tracker so PerfSample.jsFps is populated.
 ReactNativePerfStats.start(1000);
 
 // Show the floating overlay (drag to reposition).
@@ -26,36 +28,43 @@ ReactNativePerfStats.showOverlay();
 
 // One-shot read without touching the overlay timer.
 const sample = await ReactNativePerfStats.sample();
-console.log(sample); // { cpu: 12.3, rss: 187654144, timestamp: 1730000000000 }
+console.log(sample);
+// { cpu: 12.3, rss: 187654144, uiFps: 59, jsFps: 60, timestamp: 1730000000000 }
 
-// Tear down.
+// Tear down. Also stops the JS-side rAF tracker.
 ReactNativePerfStats.hideOverlay();
 ReactNativePerfStats.stop();
 ```
 
 ### `PerfSample`
 
-| field       | unit                       | notes                                                                                                  |
-| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `cpu`       | percent of one core        | `(Δcpu / Δwall) * 100`. May exceed 100 on multi-core saturation. First sample after launch is `0`.     |
-| `rss`       | bytes                      | iOS `phys_footprint`, Android `VmRSS`.                                                                 |
-| `timestamp` | ms since unix epoch        | Wall-clock at sample time.                                                                             |
+| field       | unit                  | notes                                                                                                  |
+| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `cpu`       | percent of one core   | `(Δcpu / Δwall) * 100`. May exceed 100 on multi-core saturation. First sample after launch is `0`.     |
+| `rss`       | bytes                 | iOS `phys_footprint`, Android `VmRSS`.                                                                 |
+| `uiFps`     | frames per second     | UI thread frame rate over the last sampling window. `0` until at least one window has elapsed.         |
+| `jsFps`     | frames per second     | JS thread rAF count. `0` unless `startJsFpsTracker()` has been called and reported at least once.      |
+| `timestamp` | ms since unix epoch   | Wall-clock at sample time.                                                                             |
 
 ### API
 
-- `start(intervalMs: number): void` — minimum interval is clamped to 200 ms.
-- `stop(): void` — also hides the overlay.
+- `start(intervalMs: number): void` — minimum interval is clamped to 200 ms. Also starts the JS-side rAF tracker (matched to `intervalMs`) so `jsFps` flows automatically.
+- `stop(): void` — stops the JS-side tracker, the native sampler, and hides the overlay.
 - `showOverlay(): void` / `hideOverlay(): void` — overlay shows `--` until `start` runs.
 - `sample(): Promise<PerfSample>` — runs off the JS thread, shares baseline with the overlay sampler.
+- `setJsFpsHint(fps: number): void` — low-level escape hatch; normally driven by the auto-managed tracker.
+- `startJsFpsTracker(reportIntervalMs?: number): void` / `stopJsFpsTracker(): void` — manual control of the JS-side rAF tracker. Useful if you want JS FPS without enabling the native sampler. Calling `startJsFpsTracker` with a different `reportIntervalMs` while running restarts the loop with the new interval.
 
 ### Anomaly logging
 
 While the sampler is running, the native side emits a warn to `@onekeyfe/react-native-native-logger` (`OneKeyLog.warn`, tag `PerfStats`) whenever a metric stays over its threshold for **5 consecutive samples**. Each category has an independent **30 s cooldown** so a sustained spike produces one log every 30 s rather than one per sample.
 
-| metric | threshold |
-| ------ | --------- |
-| CPU    | ≥ 150 %   |
-| RSS    | ≥ 800 MB  |
+| metric | threshold        |
+| ------ | ---------------- |
+| CPU    | ≥ 150 %          |
+| RSS    | ≥ 800 MB         |
+| UI FPS | ≤ 45 fps (and > 0) |
+| JS FPS | ≤ 30 fps (and > 0) |
 
 One-off `sample()` calls do **not** trip this path — only the periodic timer started by `start()` does.
 

package/android/src/main/java/com/margelo/nitro/reactnativeperfstats/ReactNativePerfStats.kt

@@ -12,10 +12,12 @@ import android.os.HandlerThread
 import android.os.Looper
 import android.os.SystemClock
 import android.util.TypedValue
+import android.view.Choreographer
 import android.view.Gravity
 import android.view.MotionEvent
 import android.view.WindowManager
 import android.widget.TextView
+import java.util.concurrent.atomic.AtomicInteger
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
@@ -37,8 +39,18 @@ private const val CLOCK_TICKS_PER_SECOND = 100L
 private const val CPU_ANOMALY_PCT = 150.0
 // 800 MiB.
 private const val RSS_ANOMALY_BYTES = 838_860_800.0
+// Below ~45 fps the UI thread feels janky on a 60 Hz panel. On 90/120 Hz
+// devices this still represents a clearly degraded experience, so we keep
+// one threshold rather than introducing refresh-rate detection.
+private const val UI_FPS_ANOMALY_BELOW = 45.0
+// Below ~30 fps the JS thread is missing every other frame's RAF callback.
+private const val JS_FPS_ANOMALY_BELOW = 30.0
 private const val ANOMALY_SUSTAIN_SAMPLES = 5
 private const val ANOMALY_COOLDOWN_MS = 30_000L
+// JS FPS hints older than this are treated as stale and reported as 0,
+// so the overlay doesn't keep showing a fossilised number after the
+// JS-side tracker has been stopped (or is still booting).
+private const val JS_FPS_HINT_TTL_MS = 2_000L
 
 @DoNotStrip
 class ReactNativePerfStats : HybridReactNativePerfStatsSpec() {
@@ -64,6 +76,10 @@ class ReactNativePerfStats : HybridReactNativePerfStatsSpec() {
             Sampler.takeSample()
         }
     }
+
+    override fun setJsFpsHint(fps: Double) {
+        JsFpsHolder.set(fps)
+    }
 }
 
 // ---- Sampler ----------------------------------------------------------
@@ -94,6 +110,10 @@ private object Sampler {
     private val lock = Any()
     @Volatile private var lastCpuTicks: Long = -1L
     @Volatile private var lastMonoNs: Long = -1L
+    // Last UI FPS computed by the periodic tick. takeSample() reads this
+    // directly so one-shot sample() calls do not steal frames from the
+    // UiFpsMonitor counter (which is owned by the periodic tick).
+    @Volatile private var lastUiFps: Double = 0.0
 
     // Anomaly state lives on the sampler HandlerThread (single consumer),
     // so no synchronization is needed. lastLogMs intentionally persists
@@ -101,8 +121,12 @@ private object Sampler {
     // caller toggles the sampler rapidly.
     private var cpuOverCount = 0
     private var rssOverCount = 0
+    private var uiFpsUnderCount = 0
+    private var jsFpsUnderCount = 0
     private var lastCpuLogMs = 0L
     private var lastRssLogMs = 0L
+    private var lastUiFpsLogMs = 0L
+    private var lastJsFpsLogMs = 0L
 
     fun start(intervalMsNew: Long) {
         synchronized(schedulerLock) {
@@ -116,6 +140,7 @@ private object Sampler {
             running = true
             scheduleTick(generation, handler!!)
         }
+        UiFpsMonitor.start()
     }
 
     fun stop() {
@@ -128,7 +153,9 @@ private object Sampler {
             handlerThread?.quitSafely()
             handlerThread = null
             handler = null
+            lastUiFps = 0.0
         }
+        UiFpsMonitor.stop()
         Overlay.hide()
     }
 
@@ -140,6 +167,9 @@ private object Sampler {
                     genAtStart == generation && running
                 }
                 if (!active) return
+                // Refresh the cached UI FPS *before* takeSample reads it,
+                // so the value covers exactly the just-elapsed interval.
+                lastUiFps = UiFpsMonitor.readAndReset(System.nanoTime())
                 val sample = takeSample()
                 Overlay.update(sample)
                 checkAnomalyAndLog(sample)
@@ -200,6 +230,49 @@ private object Sampler {
         } else {
             rssOverCount = 0
         }
+
+        // FPS thresholds. We require uiFps > 0 to avoid logging during the
+        // first sample (when no interval has elapsed yet); jsFps > 0 to skip
+        // when the JS-side tracker hasn't been started.
+        if (s.uiFps in 0.001..UI_FPS_ANOMALY_BELOW) {
+            uiFpsUnderCount++
+            if (uiFpsUnderCount >= ANOMALY_SUSTAIN_SAMPLES &&
+                nowMs - lastUiFpsLogMs >= ANOMALY_COOLDOWN_MS
+            ) {
+                OneKeyLog.warn(
+                    TAG,
+                    String.format(
+                        Locale.US,
+                        "Sustained low UI FPS: %.1f over %d samples",
+                        s.uiFps, uiFpsUnderCount,
+                    ),
+                )
+                lastUiFpsLogMs = nowMs
+                uiFpsUnderCount = 0
+            }
+        } else {
+            uiFpsUnderCount = 0
+        }
+
+        if (s.jsFps in 0.001..JS_FPS_ANOMALY_BELOW) {
+            jsFpsUnderCount++
+            if (jsFpsUnderCount >= ANOMALY_SUSTAIN_SAMPLES &&
+                nowMs - lastJsFpsLogMs >= ANOMALY_COOLDOWN_MS
+            ) {
+                OneKeyLog.warn(
+                    TAG,
+                    String.format(
+                        Locale.US,
+                        "Sustained low JS FPS: %.1f over %d samples",
+                        s.jsFps, jsFpsUnderCount,
+                    ),
+                )
+                lastJsFpsLogMs = nowMs
+                jsFpsUnderCount = 0
+            }
+        } else {
+            jsFpsUnderCount = 0
+        }
     }
 
     fun takeSample(): PerfSample {
@@ -230,6 +303,8 @@ private object Sampler {
         return PerfSample(
             cpu = cpuPct,
             rss = rssBytes.toDouble(),
+            uiFps = lastUiFps,
+            jsFps = JsFpsHolder.read(nowMonoNs),
             timestamp = nowWallMs,
         )
     }
@@ -282,6 +357,96 @@ private object Sampler {
     }
 }
 
+// ---- UiFpsMonitor -----------------------------------------------------
+//
+// Counts main-thread frames via Choreographer.FrameCallback. The
+// callback fires once per refresh cycle (60/90/120 Hz) when the UI
+// thread is responsive, so the per-second count is a faithful proxy
+// for "did the UI thread service its frame callbacks".
+//
+// `Choreographer.getInstance()` returns the per-thread instance, so
+// the registration must run on the main looper to observe main-thread
+// frames; the worker HandlerThread has no Choreographer.
+
+private object UiFpsMonitor {
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private val frameCounter = AtomicInteger(0)
+    @Volatile private var registered = false
+    @Volatile private var lastReadMonoNs: Long = -1L
+
+    private val callback = object : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            frameCounter.incrementAndGet()
+            if (registered) {
+                Choreographer.getInstance().postFrameCallback(this)
+            }
+        }
+    }
+
+    fun start() {
+        if (registered) return
+        registered = true
+        mainHandler.post {
+            // Re-check inside the post: a stop() may have raced ahead
+            // before this lambda ran.
+            if (!registered) return@post
+            Choreographer.getInstance().postFrameCallback(callback)
+        }
+    }
+
+    fun stop() {
+        if (!registered) return
+        registered = false
+        mainHandler.post {
+            Choreographer.getInstance().removeFrameCallback(callback)
+        }
+        frameCounter.set(0)
+        lastReadMonoNs = -1L
+    }
+
+    /**
+     * Returns the FPS observed since the previous call. The first call
+     * after [start] returns 0 because there's no baseline interval yet.
+     * Safe to invoke from any thread.
+     */
+    fun readAndReset(nowMonoNs: Long): Double {
+        val prev = lastReadMonoNs
+        val frames = frameCounter.getAndSet(0)
+        lastReadMonoNs = nowMonoNs
+        if (prev <= 0) return 0.0
+        val dWallSec = (nowMonoNs - prev).toDouble() / 1_000_000_000.0
+        if (dWallSec <= 0) return 0.0
+        return frames / dWallSec
+    }
+}
+
+// ---- JsFpsHolder ------------------------------------------------------
+//
+// Caches the most recent JS-thread FPS hint pushed via
+// `setJsFpsHint`. The value is computed entirely on the JS side via
+// the `requestAnimationFrame` ticker started by `startJsFpsTracker`,
+// then reported here. We stale out hints older than [JS_FPS_HINT_TTL_MS]
+// to avoid surfacing a fossilised number when the JS tracker has been
+// stopped or has not yet booted.
+
+private object JsFpsHolder {
+    @Volatile private var lastFps: Double = 0.0
+    @Volatile private var lastSetMonoNs: Long = -1L
+
+    fun set(fps: Double) {
+        lastFps = fps
+        lastSetMonoNs = System.nanoTime()
+    }
+
+    fun read(nowMonoNs: Long): Double {
+        val last = lastSetMonoNs
+        if (last < 0) return 0.0
+        val ageMs = (nowMonoNs - last) / 1_000_000L
+        if (ageMs > JS_FPS_HINT_TTL_MS) return 0.0
+        return lastFps
+    }
+}
+
 // ---- Overlay ----------------------------------------------------------
 //
 // Attaches a TextView via WindowManager.addView at z=1005, the AOSP slot
@@ -452,8 +617,8 @@ internal object Overlay : Application.ActivityLifecycleCallbacks {
             )
             gravity = Gravity.START
             // Min width prevents re-layout when digit count changes
-            minWidth = dp(activity, 110)
-            text = "CPU: --\nRAM: --"
+            minWidth = dp(activity, 130)
+            text = "CPU: --\nRAM: --\nUI:  --\nJS:  --"
         }
     }
 
@@ -491,7 +656,9 @@ internal object Overlay : Application.ActivityLifecycleCallbacks {
         val cpu = if (s.cpu > 0) String.format(Locale.US, "%.1f%%", s.cpu) else "--"
         val mb = s.rss / 1024.0 / 1024.0
         val mem = if (mb > 0) String.format(Locale.US, "%.1f MB", mb) else "--"
-        return "CPU: $cpu\nRAM: $mem"
+        val ui = if (s.uiFps > 0) String.format(Locale.US, "%.0f fps", s.uiFps) else "--"
+        val js = if (s.jsFps > 0) String.format(Locale.US, "%.0f fps", s.jsFps) else "--"
+        return "CPU: $cpu\nRAM: $mem\nUI:  $ui\nJS:  $js"
     }
 
     private fun dp(activity: Activity, v: Int): Int =

package/ios/ReactNativePerfStats.swift

@@ -12,8 +12,16 @@ private let kMinIntervalMs: Double = 200
 // for kAnomalyCooldownSec to avoid flooding native-logger.
 private let kCpuAnomalyPct: Double = 150.0
 private let kRssAnomalyBytes: Double = 800.0 * 1024.0 * 1024.0
+// Below ~45 fps the UI thread feels janky on a 60 Hz panel. On 90/120 Hz
+// devices this still represents a clearly degraded experience, so we keep
+// one threshold rather than introducing refresh-rate detection.
+private let kUiFpsAnomalyBelow: Double = 45.0
+// Below ~30 fps the JS thread is missing every other frame's RAF callback.
+private let kJsFpsAnomalyBelow: Double = 30.0
 private let kAnomalySustainSamples: Int = 5
 private let kAnomalyCooldownSec: Double = 30.0
+// JS FPS hints older than this are treated as stale and reported as 0.
+private let kJsFpsHintTtlSec: Double = 2.0
 
 class ReactNativePerfStats: HybridReactNativePerfStatsSpec {
 
@@ -38,6 +46,10 @@ class ReactNativePerfStats: HybridReactNativePerfStatsSpec {
             return Sampler.shared.takeSample()
         }
     }
+
+    func setJsFpsHint(fps: Double) throws {
+        JsFpsHolder.shared.set(fps: fps)
+    }
 }
 
 // MARK: - Sampler
@@ -63,8 +75,17 @@ private final class Sampler {
     // toggles the sampler rapidly.
     private var cpuOverCount: Int = 0
     private var rssOverCount: Int = 0
+    private var uiFpsUnderCount: Int = 0
+    private var jsFpsUnderCount: Int = 0
     private var lastCpuLogSec: Double = 0
     private var lastRssLogSec: Double = 0
+    private var lastUiFpsLogSec: Double = 0
+    private var lastJsFpsLogSec: Double = 0
+
+    // Last UI FPS computed by the periodic timer. takeSample() reads this
+    // directly so one-shot sample() calls do not steal frames from the
+    // UiFpsMonitor counter (which is owned by the periodic timer).
+    private var lastUiFps: Double = 0
 
     func start(intervalMs ms: Double) {
         queue.async { [weak self] in
@@ -91,6 +112,9 @@ private final class Sampler {
             )
             t.setEventHandler { [weak self] in
                 guard let self = self, self.running else { return }
+                // Refresh cached UI FPS *before* takeSample reads it, so
+                // the value covers exactly the just-elapsed interval.
+                self.lastUiFps = UiFpsMonitor.shared.readAndReset(nowSec: self.monotonicSec())
                 let s = self.takeSample()
                 Overlay.shared.update(sample: s)
                 self.checkAnomalyAndLog(sample: s)
@@ -98,6 +122,7 @@ private final class Sampler {
             self.timer = t
             t.resume()
         }
+        UiFpsMonitor.shared.start()
     }
 
     func stop() {
@@ -106,7 +131,9 @@ private final class Sampler {
             self.running = false
             self.timer?.cancel()
             self.timer = nil
+            self.lastUiFps = 0
         }
+        UiFpsMonitor.shared.stop()
         Overlay.shared.hide()
     }
 
@@ -134,6 +161,8 @@ private final class Sampler {
         return PerfSample(
             cpu: cpuPct,
             rss: Double(rssBytes),
+            uiFps: lastUiFps,
+            jsFps: JsFpsHolder.shared.read(nowSec: nowMono),
             timestamp: nowWallMs
         )
     }
@@ -181,6 +210,45 @@ private final class Sampler {
         } else {
             rssOverCount = 0
         }
+
+        // FPS thresholds. Require uiFps > 0 to avoid logging the very first
+        // sample (no interval yet), and jsFps > 0 to skip when no JS-side
+        // tracker has been started.
+        if s.uiFps > 0 && s.uiFps <= kUiFpsAnomalyBelow {
+            uiFpsUnderCount += 1
+            if uiFpsUnderCount >= kAnomalySustainSamples,
+               nowSec - lastUiFpsLogSec >= kAnomalyCooldownSec {
+                OneKeyLog.warn(
+                    kTag,
+                    String(
+                        format: "Sustained low UI FPS: %.1f over %d samples",
+                        s.uiFps, uiFpsUnderCount
+                    )
+                )
+                lastUiFpsLogSec = nowSec
+                uiFpsUnderCount = 0
+            }
+        } else {
+            uiFpsUnderCount = 0
+        }
+
+        if s.jsFps > 0 && s.jsFps <= kJsFpsAnomalyBelow {
+            jsFpsUnderCount += 1
+            if jsFpsUnderCount >= kAnomalySustainSamples,
+               nowSec - lastJsFpsLogSec >= kAnomalyCooldownSec {
+                OneKeyLog.warn(
+                    kTag,
+                    String(
+                        format: "Sustained low JS FPS: %.1f over %d samples",
+                        s.jsFps, jsFpsUnderCount
+                    )
+                )
+                lastJsFpsLogSec = nowSec
+                jsFpsUnderCount = 0
+            }
+        } else {
+            jsFpsUnderCount = 0
+        }
     }
 
     private func monotonicSec() -> Double {
@@ -234,21 +302,153 @@ private final class Sampler {
     }
 }
 
+// MARK: - UiFpsMonitor
+//
+// CADisplayLink fires once per main-thread refresh cycle (60/90/120 Hz)
+// when the UI thread is responsive, so the per-second count is a faithful
+// proxy for "did the main thread service its frame callbacks". The link
+// must be attached to the main RunLoop, so start/stop dispatch to .main.
+
+private final class UiFpsMonitor: NSObject {
+    static let shared = UiFpsMonitor()
+
+    private override init() { super.init() }
+
+    private var displayLink: CADisplayLink?
+    // Read-modify-write of frameCounter happens on the display-link
+    // callback (main thread) and on readAndReset (sampler thread), so
+    // guard with a lock. Lightweight: two integer ops per call.
+    private let counterLock = NSLock()
+    private var frameCounter: Int = 0
+    private var lastReadSec: Double = -1
+
+    func start() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            if self.displayLink != nil { return }
+            let link = CADisplayLink(target: self, selector: #selector(self.tick))
+            link.add(to: .main, forMode: .common)
+            self.displayLink = link
+        }
+    }
+
+    func stop() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.displayLink?.invalidate()
+            self.displayLink = nil
+        }
+        counterLock.lock()
+        frameCounter = 0
+        lastReadSec = -1
+        counterLock.unlock()
+    }
+
+    @objc private func tick(link: CADisplayLink) {
+        counterLock.lock()
+        frameCounter += 1
+        counterLock.unlock()
+    }
+
+    /// Returns the FPS observed since the previous call. The first call
+    /// after `start` returns 0 because there's no baseline interval yet.
+    /// Safe to invoke from any thread.
+    func readAndReset(nowSec: Double) -> Double {
+        counterLock.lock()
+        let frames = frameCounter
+        frameCounter = 0
+        let prev = lastReadSec
+        lastReadSec = nowSec
+        counterLock.unlock()
+        if prev <= 0 { return 0 }
+        let dWall = nowSec - prev
+        if dWall <= 0 { return 0 }
+        return Double(frames) / dWall
+    }
+}
+
+// MARK: - JsFpsHolder
+//
+// Caches the most recent JS-thread FPS hint pushed via `setJsFpsHint`.
+// The value is computed entirely on the JS side via the
+// `requestAnimationFrame` ticker started by `startJsFpsTracker`, then
+// reported here. Hints older than `kJsFpsHintTtlSec` are reported as 0
+// so the overlay doesn't keep showing a fossilised number after the
+// JS tracker has been stopped (or has not yet booted).
+
+private final class JsFpsHolder {
+    static let shared = JsFpsHolder()
+
+    private init() {}
+
+    private let lock = NSLock()
+    private var lastFps: Double = 0
+    private var lastSetSec: Double = -1
+
+    func set(fps: Double) {
+        let nowSec: Double = {
+            var ts = timespec()
+            if clock_gettime(CLOCK_MONOTONIC, &ts) != 0 {
+                return Date().timeIntervalSince1970
+            }
+            return Double(ts.tv_sec) + Double(ts.tv_nsec) / 1_000_000_000.0
+        }()
+        lock.lock()
+        lastFps = fps
+        lastSetSec = nowSec
+        lock.unlock()
+    }
+
+    func read(nowSec: Double) -> Double {
+        lock.lock()
+        let last = lastSetSec
+        let fps = lastFps
+        lock.unlock()
+        if last < 0 { return 0 }
+        if nowSec - last > kJsFpsHintTtlSec { return 0 }
+        return fps
+    }
+}
+
 // MARK: - Overlay
 //
-// Singleton UILabel attached to the current key UIWindow. Updates always
-// dispatch to main. No floating-window permission needed; overlay only
-// shows while the app is in the foreground.
+// Singleton overlay rendered on its own dedicated UIWindow at
+// `.alert + 1` windowLevel. The dedicated window is required because
+// React Native's <Modal> presents view controllers via UIKit's modal
+// presentation, which renders above any subview added to the host
+// app's main UIWindow — a UILabel attached to keyWindow ends up behind
+// the modal regardless of view-hierarchy z-order. A separate UIWindow
+// with a higher `windowLevel` sits above modal-presented view
+// controllers and system alerts, so the overlay stays visible.
+//
+// `OverlayPassthroughWindow` overrides `hitTest` to return nil for
+// touches outside the label, letting them fall through to the
+// underlying app windows — otherwise the overlay window would swallow
+// every tap on the screen.
 //
 // Inherits NSObject so UIPanGestureRecognizer's target/action selector
 // dispatch resolves cleanly via Obj-C runtime.
 
+private final class OverlayPassthroughWindow: UIWindow {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        let hit = super.hitTest(point, with: event)
+        // Anything that bubbles up to the window itself or its empty
+        // root view means the touch missed our overlay subview — pass it
+        // through to whatever's below this window.
+        if hit === self || hit === self.rootViewController?.view {
+            return nil
+        }
+        return hit
+    }
+}
+
 private final class Overlay: NSObject {
     static let shared = Overlay()
 
     private override init() { super.init() }
 
     private var label: UILabel?
+    private var overlayWindow: UIWindow?
     private var visible = false
 
     // `_lastSample` is written by the Sampler timer thread and read by the
@@ -308,27 +508,44 @@ private final class Overlay: NSObject {
 
     private func attach() {
         if label != nil { return }
-        guard let window = currentKeyWindow() else {
-            OneKeyLog.warn(kTag, "No key UIWindow available; overlay deferred")
+        guard let scene = currentForegroundScene() else {
+            OneKeyLog.warn(kTag, "No foreground UIWindowScene; overlay deferred")
             return
         }
 
-        let lbl = UILabel(frame: CGRect(x: 30, y: 100, width: 160, height: 60))
+        // Dedicated host VC keeps the window's view hierarchy minimal —
+        // the empty UIView serves only as the parent for the label and
+        // as the hitTest sentinel checked by OverlayPassthroughWindow.
+        let host = UIViewController()
+        host.view.backgroundColor = .clear
+
+        let window = OverlayPassthroughWindow(windowScene: scene)
+        window.frame = scene.coordinateSpace.bounds
+        // .alert is 2000 on iOS; +1 puts the overlay above modal-presented
+        // controllers, system alerts and action sheets. Status bar is
+        // .statusBar (1000), which we stay below intentionally.
+        window.windowLevel = UIWindow.Level.alert + 1
+        window.backgroundColor = .clear
+        window.isHidden = false
+        window.rootViewController = host
+
+        let lbl = UILabel(frame: CGRect(x: 30, y: 100, width: 170, height: 92))
         lbl.backgroundColor = UIColor.black.withAlphaComponent(0.7)
         lbl.layer.cornerRadius = 8
         lbl.layer.masksToBounds = true
         lbl.textColor = .white
         lbl.font = .systemFont(ofSize: 13, weight: .bold)
         lbl.textAlignment = .center
-        lbl.numberOfLines = 2
-        lbl.text = "CPU: --\nRAM: --"
+        lbl.numberOfLines = 4
+        lbl.text = "CPU: --\nRAM: --\nUI:  --\nJS:  --"
         lbl.isUserInteractionEnabled = true
 
         let pan = UIPanGestureRecognizer(target: self, action: #selector(handlePan(_:)))
         lbl.addGestureRecognizer(pan)
 
-        window.addSubview(lbl)
+        host.view.addSubview(lbl)
         label = lbl
+        overlayWindow = window
 
         if let s = lastSample {
             lbl.text = renderText(s)
@@ -338,6 +555,13 @@ private final class Overlay: NSObject {
     private func detach() {
         label?.removeFromSuperview()
         label = nil
+        // Hide before nilling so UIKit can release the window cleanly;
+        // assigning nil to rootViewController first avoids a fleeting
+        // warning when the window is torn down with a controller still
+        // attached.
+        overlayWindow?.isHidden = true
+        overlayWindow?.rootViewController = nil
+        overlayWindow = nil
     }
 
     @objc private func handlePan(_ gesture: UIPanGestureRecognizer) {
@@ -360,32 +584,24 @@ private final class Overlay: NSObject {
         let cpuStr = s.cpu > 0 ? String(format: "%.1f%%", s.cpu) : "--"
         let mb = s.rss / 1024.0 / 1024.0
         let memStr = mb > 0 ? String(format: "%.1f MB", mb) : "--"
-        return "CPU: \(cpuStr)\nRAM: \(memStr)"
+        let uiStr = s.uiFps > 0 ? String(format: "%.0f fps", s.uiFps) : "--"
+        let jsStr = s.jsFps > 0 ? String(format: "%.0f fps", s.jsFps) : "--"
+        return "CPU: \(cpuStr)\nRAM: \(memStr)\nUI:  \(uiStr)\nJS:  \(jsStr)"
     }
 
-    private func currentKeyWindow() -> UIWindow? {
-        // iOS 15+ preferred path
-        if #available(iOS 15.0, *) {
-            for scene in UIApplication.shared.connectedScenes {
-                guard
-                    let windowScene = scene as? UIWindowScene,
-                    windowScene.activationState == .foregroundActive
-                else { continue }
-                if let kw = windowScene.keyWindow {
-                    return kw
-                }
-            }
-        }
-        // Fallback: scan all connected scenes
+    /// Locate an active foreground `UIWindowScene` to host the overlay
+    /// window. Prefers `.foregroundActive`; falls back to the first
+    /// connected `UIWindowScene` so we still attach during transient
+    /// states like cold launch when no scene is `.foregroundActive` yet.
+    private func currentForegroundScene() -> UIWindowScene? {
+        var fallback: UIWindowScene?
         for scene in UIApplication.shared.connectedScenes {
-            guard let windowScene = scene as? UIWindowScene else { continue }
-            if let kw = windowScene.windows.first(where: { $0.isKeyWindow }) {
-                return kw
-            }
-            if let any = windowScene.windows.first {
-                return any
+            guard let ws = scene as? UIWindowScene else { continue }
+            if ws.activationState == .foregroundActive {
+                return ws
             }
+            if fallback == nil { fallback = ws }
         }
-        return nil
+        return fallback
     }
 }

package/lib/module/index.js

@@ -1,6 +1,87 @@
 "use strict";
 
 import { NitroModules } from 'react-native-nitro-modules';
-const ReactNativePerfStatsHybridObject = NitroModules.createHybridObject('ReactNativePerfStats');
-export const ReactNativePerfStats = ReactNativePerfStatsHybridObject;
+const nativeImpl = NitroModules.createHybridObject('ReactNativePerfStats');
+// ---- JS FPS tracker ----------------------------------------------------
+//
+// Counts frames the JS event loop services per second using
+// `requestAnimationFrame` and pushes the value to native via
+// `setJsFpsHint`. Native then surfaces it as `PerfSample.jsFps`.
+//
+// Why rAF and not a setTimeout-based ticker: rAF is scheduled by RN's
+// UIManager from the platform vsync (Choreographer / CADisplayLink)
+// and dispatched as a JS task. When the JS thread is blocked, rAF
+// callbacks are coalesced and the per-second count drops, exactly
+// reflecting "how many frame opportunities did JS service" — which is
+// what users mean by "JS FPS". A setTimeout(16) loop measures timer
+// drift, which is correlated but coarser.
+//
+// Cost: one int increment + one rAF call per frame (~60–120/s) plus one
+// `setJsFpsHint` call per second. Negligible vs. typical app workload.
+
+let jsFpsRafId = null;
+let jsFpsIntervalId = null;
+let jsFpsFrameCount = 0;
+let jsFpsCurrentInterval = null;
+
+/**
+ * Start the JS-side FPS ticker. Normally invoked automatically by
+ * `ReactNativePerfStats.start` and stopped by `.stop`; exported as
+ * an escape hatch for advanced flows (e.g. measuring JS FPS without
+ * the native sampler running).
+ *
+ * Calling with a new `reportIntervalMs` while already running
+ * restarts the loop with the new interval; calling with the same
+ * interval is a no-op.
+ */
+export function startJsFpsTracker(reportIntervalMs = 1000) {
+  if (jsFpsCurrentInterval === reportIntervalMs) return;
+  stopJsFpsTracker();
+  jsFpsCurrentInterval = reportIntervalMs;
+  const tick = () => {
+    jsFpsFrameCount += 1;
+    jsFpsRafId = requestAnimationFrame(tick);
+  };
+  jsFpsRafId = requestAnimationFrame(tick);
+  jsFpsIntervalId = setInterval(() => {
+    const fps = jsFpsFrameCount * 1000 / reportIntervalMs;
+    jsFpsFrameCount = 0;
+    nativeImpl.setJsFpsHint(fps);
+  }, reportIntervalMs);
+}
+
+/** Stop the JS-side FPS ticker. Idempotent. */
+export function stopJsFpsTracker() {
+  if (jsFpsRafId != null) {
+    cancelAnimationFrame(jsFpsRafId);
+    jsFpsRafId = null;
+  }
+  if (jsFpsIntervalId != null) {
+    clearInterval(jsFpsIntervalId);
+    jsFpsIntervalId = null;
+  }
+  jsFpsFrameCount = 0;
+  jsFpsCurrentInterval = null;
+}
+
+// `start` / `stop` wrap the native sampler so the JS-side rAF tracker
+// shares its lifetime: callers never have to remember to enable it
+// separately, and `PerfSample.jsFps` is populated as soon as the
+// sampler is running. Other methods pass straight through to the
+// HybridObject.
+
+export const ReactNativePerfStats = {
+  start(intervalMs) {
+    nativeImpl.start(intervalMs);
+    startJsFpsTracker(intervalMs);
+  },
+  stop() {
+    stopJsFpsTracker();
+    nativeImpl.stop();
+  },
+  showOverlay: () => nativeImpl.showOverlay(),
+  hideOverlay: () => nativeImpl.hideOverlay(),
+  sample: () => nativeImpl.sample(),
+  setJsFpsHint: fps => nativeImpl.setJsFpsHint(fps)
+};
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["NitroModules","ReactNativePerfStatsHybridObject","createHybridObject","ReactNativePerfStats"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,SAASA,YAAY,QAAQ,4BAA4B;AAGzD,MAAMC,gCAAgC,GACpCD,YAAY,CAACE,kBAAkB,CAA2B,sBAAsB,CAAC;AAEnF,OAAO,MAAMC,oBAAoB,GAAGF,gCAAgC","ignoreList":[]}
+{"version":3,"names":["NitroModules","nativeImpl","createHybridObject","jsFpsRafId","jsFpsIntervalId","jsFpsFrameCount","jsFpsCurrentInterval","startJsFpsTracker","reportIntervalMs","stopJsFpsTracker","tick","requestAnimationFrame","setInterval","fps","setJsFpsHint","cancelAnimationFrame","clearInterval","ReactNativePerfStats","start","intervalMs","stop","showOverlay","hideOverlay","sample"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,SAASA,YAAY,QAAQ,4BAA4B;AAGzD,MAAMC,UAAU,GACdD,YAAY,CAACE,kBAAkB,CAA2B,sBAAsB,CAAC;AAInF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,IAAIC,UAAyB,GAAG,IAAI;AACpC,IAAIC,eAAsD,GAAG,IAAI;AACjE,IAAIC,eAAe,GAAG,CAAC;AACvB,IAAIC,oBAAmC,GAAG,IAAI;;AAE9C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,iBAAiBA,CAACC,gBAAwB,GAAG,IAAI,EAAQ;EACvE,IAAIF,oBAAoB,KAAKE,gBAAgB,EAAE;EAC/CC,gBAAgB,CAAC,CAAC;EAClBH,oBAAoB,GAAGE,gBAAgB;EAEvC,MAAME,IAAI,GAAGA,CAAA,KAAM;IACjBL,eAAe,IAAI,CAAC;IACpBF,UAAU,GAAGQ,qBAAqB,CAACD,IAAI,CAAC;EAC1C,CAAC;EACDP,UAAU,GAAGQ,qBAAqB,CAACD,IAAI,CAAC;EAExCN,eAAe,GAAGQ,WAAW,CAAC,MAAM;IAClC,MAAMC,GAAG,GAAIR,eAAe,GAAG,IAAI,GAAIG,gBAAgB;IACvDH,eAAe,GAAG,CAAC;IACnBJ,UAAU,CAACa,YAAY,CAACD,GAAG,CAAC;EAC9B,CAAC,EAAEL,gBAAgB,CAAC;AACtB;;AAEA;AACA,OAAO,SAASC,gBAAgBA,CAAA,EAAS;EACvC,IAAIN,UAAU,IAAI,IAAI,EAAE;IACtBY,oBAAoB,CAACZ,UAAU,CAAC;IAChCA,UAAU,GAAG,IAAI;EACnB;EACA,IAAIC,eAAe,IAAI,IAAI,EAAE;IAC3BY,aAAa,CAACZ,eAAe,CAAC;IAC9BA,eAAe,GAAG,IAAI;EACxB;EACAC,eAAe,GAAG,CAAC;EACnBC,oBAAoB,GAAG,IAAI;AAC7B;;AAEA;AACA;AACA;AACA;AACA;;AAEA,OAAO,MAAMW,oBAAoB,GAAG;EAClCC,KAAKA,CAACC,UAAkB,EAAQ;IAC9BlB,UAAU,CAACiB,KAAK,CAACC,UAAU,CAAC;IAC5BZ,iBAAiB,CAACY,UAAU,CAAC;EAC/B,CAAC;EACDC,IAAIA,CAAA,EAAS;IACXX,gBAAgB,CAAC,CAAC;IAClBR,UAAU,CAACmB,IAAI,CAAC,CAAC;EACnB,CAAC;EACDC,WAAW,EAAEA,CAAA,KAAYpB,UAAU,CAACoB,WAAW,CAAC,CAAC;EACjDC,WAAW,EAAEA,CAAA,KAAYrB,UAAU,CAACqB,WAAW,CAAC,CAAC;EACjDC,MAAM,EAAEA,CAAA,KAAMtB,UAAU,CAACsB,MAAM,CAAC,CAAC;EACjCT,YAAY,EAAGD,GAAW,IAAWZ,UAAU,CAACa,YAAY,CAACD,GAAG;AAClE,CAAC","ignoreList":[]}

package/lib/typescript/src/ReactNativePerfStats.nitro.d.ts

@@ -9,6 +9,18 @@ export interface PerfSample {
     cpu: number;
     /** Resident set size in bytes. iOS: phys_footprint; Android: VmRSS. */
     rss: number;
+    /**
+     * UI thread frame rate, frames per second over the last 1 s window.
+     * Measured on the platform's main thread via Choreographer (Android)
+     * or CADisplayLink (iOS). `0` until at least one window has elapsed.
+     */
+    uiFps: number;
+    /**
+     * JS thread frame rate, frames per second reported by the JS-side
+     * `requestAnimationFrame` ticker (see `startJsFpsTracker`). `0` if
+     * the tracker has not been started or no hint has been received yet.
+     */
+    jsFps: number;
     /** Wall-clock timestamp (ms since unix epoch) when the sample was taken. */
     timestamp: number;
 }
@@ -47,5 +59,15 @@ export interface ReactNativePerfStats extends HybridObject<{
      * Shares the same delta baseline as the overlay sampler.
      */
     sample(): Promise<PerfSample>;
+    /**
+     * Push the latest JS-thread frame count from the JS-side
+     * `requestAnimationFrame` ticker. Native stores the value and
+     * surfaces it as `PerfSample.jsFps` on the next sample. Cheap;
+     * intended to be called once per second.
+     *
+     * Prefer the `startJsFpsTracker` helper exported from JS rather
+     * than calling this directly.
+     */
+    setJsFpsHint(fps: number): void;
 }
 //# sourceMappingURL=ReactNativePerfStats.nitro.d.ts.map

package/lib/typescript/src/ReactNativePerfStats.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReactNativePerfStats.nitro.d.ts","sourceRoot":"","sources":["../../../src/ReactNativePerfStats.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBACf,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IACzD;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC,+EAA+E;IAC/E,IAAI,IAAI,IAAI,CAAC;IAEb;;;;;;;;;OASG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB,gFAAgF;IAChF,WAAW,IAAI,IAAI,CAAC;IAEpB;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/B"}
+{"version":3,"file":"ReactNativePerfStats.nitro.d.ts","sourceRoot":"","sources":["../../../src/ReactNativePerfStats.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBACf,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IACzD;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC,+EAA+E;IAC/E,IAAI,IAAI,IAAI,CAAC;IAEb;;;;;;;;;OASG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB,gFAAgF;IAChF,WAAW,IAAI,IAAI,CAAC;IAEpB;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE9B;;;;;;;;OAQG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC"}

package/lib/typescript/src/index.d.ts

@@ -1,4 +1,23 @@
-import type { ReactNativePerfStats as ReactNativePerfStatsType } from './ReactNativePerfStats.nitro';
-export declare const ReactNativePerfStats: ReactNativePerfStatsType;
 export type * from './ReactNativePerfStats.nitro';
+/**
+ * Start the JS-side FPS ticker. Normally invoked automatically by
+ * `ReactNativePerfStats.start` and stopped by `.stop`; exported as
+ * an escape hatch for advanced flows (e.g. measuring JS FPS without
+ * the native sampler running).
+ *
+ * Calling with a new `reportIntervalMs` while already running
+ * restarts the loop with the new interval; calling with the same
+ * interval is a no-op.
+ */
+export declare function startJsFpsTracker(reportIntervalMs?: number): void;
+/** Stop the JS-side FPS ticker. Idempotent. */
+export declare function stopJsFpsTracker(): void;
+export declare const ReactNativePerfStats: {
+    start(intervalMs: number): void;
+    stop(): void;
+    showOverlay: () => void;
+    hideOverlay: () => void;
+    sample: () => Promise<import("./ReactNativePerfStats.nitro").PerfSample>;
+    setJsFpsHint: (fps: number) => void;
+};
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,IAAI,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAKrG,eAAO,MAAM,oBAAoB,0BAAmC,CAAC;AACrE,mBAAmB,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAMA,mBAAmB,8BAA8B,CAAC;AAwBlD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,GAAE,MAAa,GAAG,IAAI,CAgBvE;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,IAAI,IAAI,CAWvC;AAQD,eAAO,MAAM,oBAAoB;sBACb,MAAM,GAAG,IAAI;YAIvB,IAAI;uBAIK,IAAI;uBACJ,IAAI;;wBAED,MAAM,KAAG,IAAI;CAClC,CAAC"}

package/nitrogen/generated/android/c++/JHybridReactNativePerfStatsSpec.cpp

@@ -79,5 +79,9 @@ namespace margelo::nitro::reactnativeperfstats {
       return __promise;
     }();
   }
+  void JHybridReactNativePerfStatsSpec::setJsFpsHint(double fps) {
+    static const auto method = javaClassStatic()->getMethod<void(double /* fps */)>("setJsFpsHint");
+    method(_javaPart, fps);
+  }
 
 } // namespace margelo::nitro::reactnativeperfstats

package/nitrogen/generated/android/c++/JHybridReactNativePerfStatsSpec.hpp

@@ -59,6 +59,7 @@ namespace margelo::nitro::reactnativeperfstats {
     void showOverlay() override;
     void hideOverlay() override;
     std::shared_ptr<Promise<PerfSample>> sample() override;
+    void setJsFpsHint(double fps) override;
 
   private:
     friend HybridBase;

package/nitrogen/generated/android/c++/JPerfSample.hpp

@@ -35,11 +35,17 @@ namespace margelo::nitro::reactnativeperfstats {
       double cpu = this->getFieldValue(fieldCpu);
       static const auto fieldRss = clazz->getField<double>("rss");
       double rss = this->getFieldValue(fieldRss);
+      static const auto fieldUiFps = clazz->getField<double>("uiFps");
+      double uiFps = this->getFieldValue(fieldUiFps);
+      static const auto fieldJsFps = clazz->getField<double>("jsFps");
+      double jsFps = this->getFieldValue(fieldJsFps);
       static const auto fieldTimestamp = clazz->getField<double>("timestamp");
       double timestamp = this->getFieldValue(fieldTimestamp);
       return PerfSample(
         cpu,
         rss,
+        uiFps,
+        jsFps,
         timestamp
       );
     }
@@ -50,13 +56,15 @@ namespace margelo::nitro::reactnativeperfstats {
      */
     [[maybe_unused]]
     static jni::local_ref<JPerfSample::javaobject> fromCpp(const PerfSample& value) {
-      using JSignature = JPerfSample(double, double, double);
+      using JSignature = JPerfSample(double, double, double, double, double);
       static const auto clazz = javaClassStatic();
       static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
       return create(
         clazz,
         value.cpu,
         value.rss,
+        value.uiFps,
+        value.jsFps,
         value.timestamp
       );
     }

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativeperfstats/HybridReactNativePerfStatsSpec.kt

@@ -65,6 +65,10 @@ abstract class HybridReactNativePerfStatsSpec: HybridObject() {
   @DoNotStrip
   @Keep
   abstract fun sample(): Promise<PerfSample>
+  
+  @DoNotStrip
+  @Keep
+  abstract fun setJsFpsHint(fps: Double): Unit
 
   private external fun initHybrid(): HybridData
 

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativeperfstats/PerfSample.kt

@@ -25,6 +25,12 @@ data class PerfSample(
   val rss: Double,
   @DoNotStrip
   @Keep
+  val uiFps: Double,
+  @DoNotStrip
+  @Keep
+  val jsFps: Double,
+  @DoNotStrip
+  @Keep
   val timestamp: Double
 ) {
   /* primary constructor */
@@ -37,8 +43,8 @@ data class PerfSample(
     @Keep
     @Suppress("unused")
     @JvmStatic
-    private fun fromCpp(cpu: Double, rss: Double, timestamp: Double): PerfSample {
-      return PerfSample(cpu, rss, timestamp)
+    private fun fromCpp(cpu: Double, rss: Double, uiFps: Double, jsFps: Double, timestamp: Double): PerfSample {
+      return PerfSample(cpu, rss, uiFps, jsFps, timestamp)
     }
   }
 }

package/nitrogen/generated/ios/c++/HybridReactNativePerfStatsSpecSwift.hpp

@@ -94,6 +94,12 @@ namespace margelo::nitro::reactnativeperfstats {
       auto __value = std::move(__result.value());
       return __value;
     }
+    inline void setJsFpsHint(double fps) override {
+      auto __result = _swiftPart.setJsFpsHint(std::forward<decltype(fps)>(fps));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
 
   private:
     ReactNativePerfStats::HybridReactNativePerfStatsSpec_cxx _swiftPart;

package/nitrogen/generated/ios/swift/HybridReactNativePerfStatsSpec.swift

@@ -19,6 +19,7 @@ public protocol HybridReactNativePerfStatsSpec_protocol: HybridObject {
   func showOverlay() throws -> Void
   func hideOverlay() throws -> Void
   func sample() throws -> Promise<PerfSample>
+  func setJsFpsHint(fps: Double) throws -> Void
 }
 
 public extension HybridReactNativePerfStatsSpec_protocol {

package/nitrogen/generated/ios/swift/HybridReactNativePerfStatsSpec_cxx.swift

@@ -179,4 +179,15 @@ open class HybridReactNativePerfStatsSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_PerfSample___(__exceptionPtr)
     }
   }
+  
+  @inline(__always)
+  public final func setJsFpsHint(fps: Double) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.setJsFpsHint(fps: fps)
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
 }

package/nitrogen/generated/ios/swift/PerfSample.swift

@@ -19,8 +19,8 @@ public extension PerfSample {
   /**
    * Create a new instance of `PerfSample`.
    */
-  init(cpu: Double, rss: Double, timestamp: Double) {
-    self.init(cpu, rss, timestamp)
+  init(cpu: Double, rss: Double, uiFps: Double, jsFps: Double, timestamp: Double) {
+    self.init(cpu, rss, uiFps, jsFps, timestamp)
   }
 
   var cpu: Double {
@@ -45,6 +45,28 @@ public extension PerfSample {
     }
   }
   
+  var uiFps: Double {
+    @inline(__always)
+    get {
+      return self.__uiFps
+    }
+    @inline(__always)
+    set {
+      self.__uiFps = newValue
+    }
+  }
+  
+  var jsFps: Double {
+    @inline(__always)
+    get {
+      return self.__jsFps
+    }
+    @inline(__always)
+    set {
+      self.__jsFps = newValue
+    }
+  }
+  
   var timestamp: Double {
     @inline(__always)
     get {

package/nitrogen/generated/shared/c++/HybridReactNativePerfStatsSpec.cpp

@@ -19,6 +19,7 @@ namespace margelo::nitro::reactnativeperfstats {
       prototype.registerHybridMethod("showOverlay", &HybridReactNativePerfStatsSpec::showOverlay);
       prototype.registerHybridMethod("hideOverlay", &HybridReactNativePerfStatsSpec::hideOverlay);
       prototype.registerHybridMethod("sample", &HybridReactNativePerfStatsSpec::sample);
+      prototype.registerHybridMethod("setJsFpsHint", &HybridReactNativePerfStatsSpec::setJsFpsHint);
     });
   }
 

package/nitrogen/generated/shared/c++/HybridReactNativePerfStatsSpec.hpp

@@ -55,6 +55,7 @@ namespace margelo::nitro::reactnativeperfstats {
       virtual void showOverlay() = 0;
       virtual void hideOverlay() = 0;
       virtual std::shared_ptr<Promise<PerfSample>> sample() = 0;
+      virtual void setJsFpsHint(double fps) = 0;
 
     protected:
       // Hybrid Setup

package/nitrogen/generated/shared/c++/PerfSample.hpp

@@ -36,11 +36,13 @@ namespace margelo::nitro::reactnativeperfstats {
   public:
     double cpu     SWIFT_PRIVATE;
     double rss     SWIFT_PRIVATE;
+    double uiFps     SWIFT_PRIVATE;
+    double jsFps     SWIFT_PRIVATE;
     double timestamp     SWIFT_PRIVATE;
 
   public:
     PerfSample() = default;
-    explicit PerfSample(double cpu, double rss, double timestamp): cpu(cpu), rss(rss), timestamp(timestamp) {}
+    explicit PerfSample(double cpu, double rss, double uiFps, double jsFps, double timestamp): cpu(cpu), rss(rss), uiFps(uiFps), jsFps(jsFps), timestamp(timestamp) {}
   };
 
 } // namespace margelo::nitro::reactnativeperfstats
@@ -55,6 +57,8 @@ namespace margelo::nitro {
       return margelo::nitro::reactnativeperfstats::PerfSample(
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "cpu")),
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "rss")),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "uiFps")),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "jsFps")),
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "timestamp"))
       );
     }
@@ -62,6 +66,8 @@ namespace margelo::nitro {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, "cpu", JSIConverter<double>::toJSI(runtime, arg.cpu));
       obj.setProperty(runtime, "rss", JSIConverter<double>::toJSI(runtime, arg.rss));
+      obj.setProperty(runtime, "uiFps", JSIConverter<double>::toJSI(runtime, arg.uiFps));
+      obj.setProperty(runtime, "jsFps", JSIConverter<double>::toJSI(runtime, arg.jsFps));
       obj.setProperty(runtime, "timestamp", JSIConverter<double>::toJSI(runtime, arg.timestamp));
       return obj;
     }
@@ -75,6 +81,8 @@ namespace margelo::nitro {
       }
       if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "cpu"))) return false;
       if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "rss"))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "uiFps"))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "jsFps"))) return false;
       if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "timestamp"))) return false;
       return true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-perf-stats",
-  "version": "3.0.26",
+  "version": "3.0.28",
   "description": "react-native-perf-stats",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/ReactNativePerfStats.nitro.ts

@@ -10,6 +10,18 @@ export interface PerfSample {
   cpu: number;
   /** Resident set size in bytes. iOS: phys_footprint; Android: VmRSS. */
   rss: number;
+  /**
+   * UI thread frame rate, frames per second over the last 1 s window.
+   * Measured on the platform's main thread via Choreographer (Android)
+   * or CADisplayLink (iOS). `0` until at least one window has elapsed.
+   */
+  uiFps: number;
+  /**
+   * JS thread frame rate, frames per second reported by the JS-side
+   * `requestAnimationFrame` ticker (see `startJsFpsTracker`). `0` if
+   * the tracker has not been started or no hint has been received yet.
+   */
+  jsFps: number;
   /** Wall-clock timestamp (ms since unix epoch) when the sample was taken. */
   timestamp: number;
 }
@@ -51,4 +63,15 @@ export interface ReactNativePerfStats
    * Shares the same delta baseline as the overlay sampler.
    */
   sample(): Promise<PerfSample>;
+
+  /**
+   * Push the latest JS-thread frame count from the JS-side
+   * `requestAnimationFrame` ticker. Native stores the value and
+   * surfaces it as `PerfSample.jsFps` on the next sample. Cheap;
+   * intended to be called once per second.
+   *
+   * Prefer the `startJsFpsTracker` helper exported from JS rather
+   * than calling this directly.
+   */
+  setJsFpsHint(fps: number): void;
 }

package/src/index.tsx

@@ -1,8 +1,92 @@
 import { NitroModules } from 'react-native-nitro-modules';
 import type { ReactNativePerfStats as ReactNativePerfStatsType } from './ReactNativePerfStats.nitro';
 
-const ReactNativePerfStatsHybridObject =
+const nativeImpl =
   NitroModules.createHybridObject<ReactNativePerfStatsType>('ReactNativePerfStats');
 
-export const ReactNativePerfStats = ReactNativePerfStatsHybridObject;
 export type * from './ReactNativePerfStats.nitro';
+
+// ---- JS FPS tracker ----------------------------------------------------
+//
+// Counts frames the JS event loop services per second using
+// `requestAnimationFrame` and pushes the value to native via
+// `setJsFpsHint`. Native then surfaces it as `PerfSample.jsFps`.
+//
+// Why rAF and not a setTimeout-based ticker: rAF is scheduled by RN's
+// UIManager from the platform vsync (Choreographer / CADisplayLink)
+// and dispatched as a JS task. When the JS thread is blocked, rAF
+// callbacks are coalesced and the per-second count drops, exactly
+// reflecting "how many frame opportunities did JS service" — which is
+// what users mean by "JS FPS". A setTimeout(16) loop measures timer
+// drift, which is correlated but coarser.
+//
+// Cost: one int increment + one rAF call per frame (~60–120/s) plus one
+// `setJsFpsHint` call per second. Negligible vs. typical app workload.
+
+let jsFpsRafId: number | null = null;
+let jsFpsIntervalId: ReturnType<typeof setInterval> | null = null;
+let jsFpsFrameCount = 0;
+let jsFpsCurrentInterval: number | null = null;
+
+/**
+ * Start the JS-side FPS ticker. Normally invoked automatically by
+ * `ReactNativePerfStats.start` and stopped by `.stop`; exported as
+ * an escape hatch for advanced flows (e.g. measuring JS FPS without
+ * the native sampler running).
+ *
+ * Calling with a new `reportIntervalMs` while already running
+ * restarts the loop with the new interval; calling with the same
+ * interval is a no-op.
+ */
+export function startJsFpsTracker(reportIntervalMs: number = 1000): void {
+  if (jsFpsCurrentInterval === reportIntervalMs) return;
+  stopJsFpsTracker();
+  jsFpsCurrentInterval = reportIntervalMs;
+
+  const tick = () => {
+    jsFpsFrameCount += 1;
+    jsFpsRafId = requestAnimationFrame(tick);
+  };
+  jsFpsRafId = requestAnimationFrame(tick);
+
+  jsFpsIntervalId = setInterval(() => {
+    const fps = (jsFpsFrameCount * 1000) / reportIntervalMs;
+    jsFpsFrameCount = 0;
+    nativeImpl.setJsFpsHint(fps);
+  }, reportIntervalMs);
+}
+
+/** Stop the JS-side FPS ticker. Idempotent. */
+export function stopJsFpsTracker(): void {
+  if (jsFpsRafId != null) {
+    cancelAnimationFrame(jsFpsRafId);
+    jsFpsRafId = null;
+  }
+  if (jsFpsIntervalId != null) {
+    clearInterval(jsFpsIntervalId);
+    jsFpsIntervalId = null;
+  }
+  jsFpsFrameCount = 0;
+  jsFpsCurrentInterval = null;
+}
+
+// `start` / `stop` wrap the native sampler so the JS-side rAF tracker
+// shares its lifetime: callers never have to remember to enable it
+// separately, and `PerfSample.jsFps` is populated as soon as the
+// sampler is running. Other methods pass straight through to the
+// HybridObject.
+
+export const ReactNativePerfStats = {
+  start(intervalMs: number): void {
+    nativeImpl.start(intervalMs);
+    startJsFpsTracker(intervalMs);
+  },
+  stop(): void {
+    stopJsFpsTracker();
+    nativeImpl.stop();
+  },
+  showOverlay: (): void => nativeImpl.showOverlay(),
+  hideOverlay: (): void => nativeImpl.hideOverlay(),
+  sample: () => nativeImpl.sample(),
+  setJsFpsHint: (fps: number): void => nativeImpl.setJsFpsHint(fps),
+};