@onekeyfe/react-native-perf-stats 3.0.35 → 3.0.37

package/nitrogen/generated/ios/ReactNativePerfStats-Swift-Cxx-Bridge.hpp

@@ -10,6 +10,10 @@
 // Forward declarations of C++ defined types
 // Forward declaration of `HybridReactNativePerfStatsSpec` to properly resolve imports.
 namespace margelo::nitro::reactnativeperfstats { class HybridReactNativePerfStatsSpec; }
+// Forward declaration of `MemoryWarningEvent` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { struct MemoryWarningEvent; }
+// Forward declaration of `MemoryWarningLevel` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { enum class MemoryWarningLevel; }
 // Forward declaration of `PerfSample` to properly resolve imports.
 namespace margelo::nitro::reactnativeperfstats { struct PerfSample; }
 
@@ -19,6 +23,8 @@ namespace ReactNativePerfStats { class HybridReactNativePerfStatsSpec_cxx; }
 
 // Include C++ defined types
 #include "HybridReactNativePerfStatsSpec.hpp"
+#include "MemoryWarningEvent.hpp"
+#include "MemoryWarningLevel.hpp"
 #include "PerfSample.hpp"
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/PromiseHolder.hpp>
@@ -89,6 +95,28 @@ namespace margelo::nitro::reactnativeperfstats::bridge::swift {
     return Func_void_std__exception_ptr_Wrapper(std::move(value));
   }
   
+  // pragma MARK: std::function<void(const MemoryWarningEvent& /* event */)>
+  /**
+   * Specialized version of `std::function<void(const MemoryWarningEvent&)>`.
+   */
+  using Func_void_MemoryWarningEvent = std::function<void(const MemoryWarningEvent& /* event */)>;
+  /**
+   * Wrapper class for a `std::function<void(const MemoryWarningEvent& / * event * /)>`, this can be used from Swift.
+   */
+  class Func_void_MemoryWarningEvent_Wrapper final {
+  public:
+    explicit Func_void_MemoryWarningEvent_Wrapper(std::function<void(const MemoryWarningEvent& /* event */)>&& func): _function(std::make_unique<std::function<void(const MemoryWarningEvent& /* event */)>>(std::move(func))) {}
+    inline void call(MemoryWarningEvent event) const noexcept {
+      _function->operator()(event);
+    }
+  private:
+    std::unique_ptr<std::function<void(const MemoryWarningEvent& /* event */)>> _function;
+  } SWIFT_NONCOPYABLE;
+  Func_void_MemoryWarningEvent create_Func_void_MemoryWarningEvent(void* NON_NULL swiftClosureWrapper) noexcept;
+  inline Func_void_MemoryWarningEvent_Wrapper wrap_Func_void_MemoryWarningEvent(Func_void_MemoryWarningEvent value) noexcept {
+    return Func_void_MemoryWarningEvent_Wrapper(std::move(value));
+  }
+  
   // pragma MARK: std::shared_ptr<HybridReactNativePerfStatsSpec>
   /**
    * Specialized version of `std::shared_ptr<HybridReactNativePerfStatsSpec>`.
@@ -118,5 +146,14 @@ namespace margelo::nitro::reactnativeperfstats::bridge::swift {
   inline Result_std__shared_ptr_Promise_PerfSample___ create_Result_std__shared_ptr_Promise_PerfSample___(const std::exception_ptr& error) noexcept {
     return Result<std::shared_ptr<Promise<PerfSample>>>::withError(error);
   }
+  
+  // pragma MARK: Result<double>
+  using Result_double_ = Result<double>;
+  inline Result_double_ create_Result_double_(double value) noexcept {
+    return Result<double>::withValue(std::move(value));
+  }
+  inline Result_double_ create_Result_double_(const std::exception_ptr& error) noexcept {
+    return Result<double>::withError(error);
+  }
 
 } // namespace margelo::nitro::reactnativeperfstats::bridge::swift

package/nitrogen/generated/ios/ReactNativePerfStats-Swift-Cxx-Umbrella.hpp

@@ -10,15 +10,22 @@
 // Forward declarations of C++ defined types
 // Forward declaration of `HybridReactNativePerfStatsSpec` to properly resolve imports.
 namespace margelo::nitro::reactnativeperfstats { class HybridReactNativePerfStatsSpec; }
+// Forward declaration of `MemoryWarningEvent` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { struct MemoryWarningEvent; }
+// Forward declaration of `MemoryWarningLevel` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { enum class MemoryWarningLevel; }
 // Forward declaration of `PerfSample` to properly resolve imports.
 namespace margelo::nitro::reactnativeperfstats { struct PerfSample; }
 
 // Include C++ defined types
 #include "HybridReactNativePerfStatsSpec.hpp"
+#include "MemoryWarningEvent.hpp"
+#include "MemoryWarningLevel.hpp"
 #include "PerfSample.hpp"
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/Result.hpp>
 #include <exception>
+#include <functional>
 #include <memory>
 
 // C++ helpers for Swift

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

@@ -14,9 +14,16 @@ namespace ReactNativePerfStats { class HybridReactNativePerfStatsSpec_cxx; }
 
 // Forward declaration of `PerfSample` to properly resolve imports.
 namespace margelo::nitro::reactnativeperfstats { struct PerfSample; }
+// Forward declaration of `MemoryWarningEvent` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { struct MemoryWarningEvent; }
+// Forward declaration of `MemoryWarningLevel` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { enum class MemoryWarningLevel; }
 
 #include "PerfSample.hpp"
 #include <NitroModules/Promise.hpp>
+#include "MemoryWarningEvent.hpp"
+#include <functional>
+#include "MemoryWarningLevel.hpp"
 
 #include "ReactNativePerfStats-Swift-Cxx-Umbrella.hpp"
 
@@ -100,6 +107,26 @@ namespace margelo::nitro::reactnativeperfstats {
         std::rethrow_exception(__result.error());
       }
     }
+    inline double addMemoryWarningListener(const std::function<void(const MemoryWarningEvent& /* event */)>& callback) override {
+      auto __result = _swiftPart.addMemoryWarningListener(callback);
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+      auto __value = std::move(__result.value());
+      return __value;
+    }
+    inline void removeMemoryWarningListener(double id) override {
+      auto __result = _swiftPart.removeMemoryWarningListener(std::forward<decltype(id)>(id));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
+    inline void cleanupNativeCaches() override {
+      auto __result = _swiftPart.cleanupNativeCaches();
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
 
   private:
     ReactNativePerfStats::HybridReactNativePerfStatsSpec_cxx _swiftPart;

package/nitrogen/generated/ios/swift/Func_void_MemoryWarningEvent.swift

@@ -0,0 +1,47 @@
+///
+/// Func_void_MemoryWarningEvent.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+import Foundation
+import NitroModules
+
+/**
+ * Wraps a Swift `(_ event: MemoryWarningEvent) -> Void` as a class.
+ * This class can be used from C++, e.g. to wrap the Swift closure as a `std::function`.
+ */
+public final class Func_void_MemoryWarningEvent {
+  public typealias bridge = margelo.nitro.reactnativeperfstats.bridge.swift
+
+  private let closure: (_ event: MemoryWarningEvent) -> Void
+
+  public init(_ closure: @escaping (_ event: MemoryWarningEvent) -> Void) {
+    self.closure = closure
+  }
+
+  @inline(__always)
+  public func call(event: MemoryWarningEvent) -> Void {
+    self.closure(event)
+  }
+
+  /**
+   * Casts this instance to a retained unsafe raw pointer.
+   * This acquires one additional strong reference on the object!
+   */
+  @inline(__always)
+  public func toUnsafe() -> UnsafeMutableRawPointer {
+    return Unmanaged.passRetained(self).toOpaque()
+  }
+
+  /**
+   * Casts an unsafe pointer to a `Func_void_MemoryWarningEvent`.
+   * The pointer has to be a retained opaque `Unmanaged<Func_void_MemoryWarningEvent>`.
+   * This removes one strong reference from the object!
+   */
+  @inline(__always)
+  public static func fromUnsafe(_ pointer: UnsafeMutableRawPointer) -> Func_void_MemoryWarningEvent {
+    return Unmanaged<Func_void_MemoryWarningEvent>.fromOpaque(pointer).takeRetainedValue()
+  }
+}

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

@@ -20,6 +20,9 @@ public protocol HybridReactNativePerfStatsSpec_protocol: HybridObject {
   func hideOverlay() throws -> Void
   func sample() throws -> Promise<PerfSample>
   func setJsFpsHint(fps: Double) throws -> Void
+  func addMemoryWarningListener(callback: @escaping (_ event: MemoryWarningEvent) -> Void) throws -> Double
+  func removeMemoryWarningListener(id: Double) throws -> Void
+  func cleanupNativeCaches() throws -> Void
 }
 
 public extension HybridReactNativePerfStatsSpec_protocol {

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

@@ -190,4 +190,43 @@ open class HybridReactNativePerfStatsSpec_cxx {
       return bridge.create_Result_void_(__exceptionPtr)
     }
   }
+  
+  @inline(__always)
+  public final func addMemoryWarningListener(callback: bridge.Func_void_MemoryWarningEvent) -> bridge.Result_double_ {
+    do {
+      let __result = try self.__implementation.addMemoryWarningListener(callback: { () -> (MemoryWarningEvent) -> Void in
+        let __wrappedFunction = bridge.wrap_Func_void_MemoryWarningEvent(callback)
+        return { (__event: MemoryWarningEvent) -> Void in
+          __wrappedFunction.call(__event)
+        }
+      }())
+      let __resultCpp = __result
+      return bridge.create_Result_double_(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_double_(__exceptionPtr)
+    }
+  }
+  
+  @inline(__always)
+  public final func removeMemoryWarningListener(id: Double) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.removeMemoryWarningListener(id: id)
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
+  
+  @inline(__always)
+  public final func cleanupNativeCaches() -> bridge.Result_void_ {
+    do {
+      try self.__implementation.cleanupNativeCaches()
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
 }

package/nitrogen/generated/ios/swift/MemoryWarningEvent.swift

@@ -0,0 +1,58 @@
+///
+/// MemoryWarningEvent.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+import Foundation
+import NitroModules
+
+/**
+ * Represents an instance of `MemoryWarningEvent`, backed by a C++ struct.
+ */
+public typealias MemoryWarningEvent = margelo.nitro.reactnativeperfstats.MemoryWarningEvent
+
+public extension MemoryWarningEvent {
+  private typealias bridge = margelo.nitro.reactnativeperfstats.bridge.swift
+
+  /**
+   * Create a new instance of `MemoryWarningEvent`.
+   */
+  init(level: MemoryWarningLevel, rss: Double, timestamp: Double) {
+    self.init(level, rss, timestamp)
+  }
+
+  var level: MemoryWarningLevel {
+    @inline(__always)
+    get {
+      return self.__level
+    }
+    @inline(__always)
+    set {
+      self.__level = newValue
+    }
+  }
+  
+  var rss: Double {
+    @inline(__always)
+    get {
+      return self.__rss
+    }
+    @inline(__always)
+    set {
+      self.__rss = newValue
+    }
+  }
+  
+  var timestamp: Double {
+    @inline(__always)
+    get {
+      return self.__timestamp
+    }
+    @inline(__always)
+    set {
+      self.__timestamp = newValue
+    }
+  }
+}

package/nitrogen/generated/ios/swift/MemoryWarningLevel.swift

@@ -0,0 +1,40 @@
+///
+/// MemoryWarningLevel.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+/**
+ * Represents the JS union `MemoryWarningLevel`, backed by a C++ enum.
+ */
+public typealias MemoryWarningLevel = margelo.nitro.reactnativeperfstats.MemoryWarningLevel
+
+public extension MemoryWarningLevel {
+  /**
+   * Get a MemoryWarningLevel for the given String value, or
+   * return `nil` if the given value was invalid/unknown.
+   */
+  init?(fromString string: String) {
+    switch string {
+      case "low":
+        self = .low
+      case "critical":
+        self = .critical
+      default:
+        return nil
+    }
+  }
+
+  /**
+   * Get the String value this MemoryWarningLevel represents.
+   */
+  var stringValue: String {
+    switch self {
+      case .low:
+        return "low"
+      case .critical:
+        return "critical"
+    }
+  }
+}

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

@@ -20,6 +20,9 @@ namespace margelo::nitro::reactnativeperfstats {
       prototype.registerHybridMethod("hideOverlay", &HybridReactNativePerfStatsSpec::hideOverlay);
       prototype.registerHybridMethod("sample", &HybridReactNativePerfStatsSpec::sample);
       prototype.registerHybridMethod("setJsFpsHint", &HybridReactNativePerfStatsSpec::setJsFpsHint);
+      prototype.registerHybridMethod("addMemoryWarningListener", &HybridReactNativePerfStatsSpec::addMemoryWarningListener);
+      prototype.registerHybridMethod("removeMemoryWarningListener", &HybridReactNativePerfStatsSpec::removeMemoryWarningListener);
+      prototype.registerHybridMethod("cleanupNativeCaches", &HybridReactNativePerfStatsSpec::cleanupNativeCaches);
     });
   }
 

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

@@ -15,9 +15,13 @@
 
 // Forward declaration of `PerfSample` to properly resolve imports.
 namespace margelo::nitro::reactnativeperfstats { struct PerfSample; }
+// Forward declaration of `MemoryWarningEvent` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { struct MemoryWarningEvent; }
 
 #include "PerfSample.hpp"
 #include <NitroModules/Promise.hpp>
+#include "MemoryWarningEvent.hpp"
+#include <functional>
 
 namespace margelo::nitro::reactnativeperfstats {
 
@@ -56,6 +60,9 @@ namespace margelo::nitro::reactnativeperfstats {
       virtual void hideOverlay() = 0;
       virtual std::shared_ptr<Promise<PerfSample>> sample() = 0;
       virtual void setJsFpsHint(double fps) = 0;
+      virtual double addMemoryWarningListener(const std::function<void(const MemoryWarningEvent& /* event */)>& callback) = 0;
+      virtual void removeMemoryWarningListener(double id) = 0;
+      virtual void cleanupNativeCaches() = 0;
 
     protected:
       // Hybrid Setup

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

@@ -0,0 +1,84 @@
+///
+/// MemoryWarningEvent.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `MemoryWarningLevel` to properly resolve imports.
+namespace margelo::nitro::reactnativeperfstats { enum class MemoryWarningLevel; }
+
+#include "MemoryWarningLevel.hpp"
+
+namespace margelo::nitro::reactnativeperfstats {
+
+  /**
+   * A struct which can be represented as a JavaScript object (MemoryWarningEvent).
+   */
+  struct MemoryWarningEvent {
+  public:
+    MemoryWarningLevel level     SWIFT_PRIVATE;
+    double rss     SWIFT_PRIVATE;
+    double timestamp     SWIFT_PRIVATE;
+
+  public:
+    MemoryWarningEvent() = default;
+    explicit MemoryWarningEvent(MemoryWarningLevel level, double rss, double timestamp): level(level), rss(rss), timestamp(timestamp) {}
+  };
+
+} // namespace margelo::nitro::reactnativeperfstats
+
+namespace margelo::nitro {
+
+  // C++ MemoryWarningEvent <> JS MemoryWarningEvent (object)
+  template <>
+  struct JSIConverter<margelo::nitro::reactnativeperfstats::MemoryWarningEvent> final {
+    static inline margelo::nitro::reactnativeperfstats::MemoryWarningEvent fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::reactnativeperfstats::MemoryWarningEvent(
+        JSIConverter<margelo::nitro::reactnativeperfstats::MemoryWarningLevel>::fromJSI(runtime, obj.getProperty(runtime, "level")),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "rss")),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, "timestamp"))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::reactnativeperfstats::MemoryWarningEvent& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, "level", JSIConverter<margelo::nitro::reactnativeperfstats::MemoryWarningLevel>::toJSI(runtime, arg.level));
+      obj.setProperty(runtime, "rss", JSIConverter<double>::toJSI(runtime, arg.rss));
+      obj.setProperty(runtime, "timestamp", JSIConverter<double>::toJSI(runtime, arg.timestamp));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<margelo::nitro::reactnativeperfstats::MemoryWarningLevel>::canConvert(runtime, obj.getProperty(runtime, "level"))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "rss"))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, "timestamp"))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

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

@@ -0,0 +1,76 @@
+///
+/// MemoryWarningLevel.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::reactnativeperfstats {
+
+  /**
+   * An enum which can be represented as a JavaScript union (MemoryWarningLevel).
+   */
+  enum class MemoryWarningLevel {
+    LOW      SWIFT_NAME(low) = 0,
+    CRITICAL      SWIFT_NAME(critical) = 1,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::reactnativeperfstats
+
+namespace margelo::nitro {
+
+  // C++ MemoryWarningLevel <> JS MemoryWarningLevel (union)
+  template <>
+  struct JSIConverter<margelo::nitro::reactnativeperfstats::MemoryWarningLevel> final {
+    static inline margelo::nitro::reactnativeperfstats::MemoryWarningLevel fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("low"): return margelo::nitro::reactnativeperfstats::MemoryWarningLevel::LOW;
+        case hashString("critical"): return margelo::nitro::reactnativeperfstats::MemoryWarningLevel::CRITICAL;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum MemoryWarningLevel - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::reactnativeperfstats::MemoryWarningLevel arg) {
+      switch (arg) {
+        case margelo::nitro::reactnativeperfstats::MemoryWarningLevel::LOW: return JSIConverter<std::string>::toJSI(runtime, "low");
+        case margelo::nitro::reactnativeperfstats::MemoryWarningLevel::CRITICAL: return JSIConverter<std::string>::toJSI(runtime, "critical");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert MemoryWarningLevel to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("low"):
+        case hashString("critical"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

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

package/src/ReactNativePerfStats.nitro.ts

@@ -13,19 +13,56 @@ export interface PerfSample {
   /**
    * 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.
+   * or CADisplayLink (iOS). `0` until at least one window has elapsed
+   * **and the sampler is running** — the underlying frame monitor only
+   * runs between `start()` and `stop()`, so one-shot `sample()` calls
+   * issued outside that window always report `0` here.
    */
   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.
+   * Same caveat as `uiFps`: one-shot `sample()` calls issued before
+   * `start()` (or after `stop()`) report `0` here.
    */
   jsFps: number;
   /** Wall-clock timestamp (ms since unix epoch) when the sample was taken. */
   timestamp: number;
 }
 
+/**
+ * Severity of a system-emitted memory pressure event, normalised across
+ * platforms.
+ *
+ * - `low`: Android `TRIM_MEMORY_RUNNING_MODERATE` /
+ *   `TRIM_MEMORY_RUNNING_LOW`. iOS does not emit this level (iOS only
+ *   fires the critical warning), so JS code should treat the absence of
+ *   `low` events on iOS as expected, not a missing signal.
+ * - `critical`: iOS `UIApplicationDidReceiveMemoryWarningNotification`;
+ *   Android `TRIM_MEMORY_RUNNING_CRITICAL` or `onLowMemory()`. Indicates
+ *   the OS is about to start killing background apps (Android) or the
+ *   app itself (iOS jetsam). Subscribers should drop everything that
+ *   can be rebuilt on demand.
+ */
+export type MemoryWarningLevel = 'low' | 'critical';
+
+export interface MemoryWarningEvent {
+  level: MemoryWarningLevel;
+  /**
+   * Process RSS in bytes at the moment the warning fired. `0` if the
+   * lookup failed.
+   *
+   * On iOS the primary source is `phys_footprint`; if that fails, the
+   * fallback path reads `resident_size`, which is semantically smaller
+   * and noisier. The two values are not directly comparable, so treat
+   * unexpected magnitude differences across reports cautiously.
+   */
+  rss: number;
+  /** Wall-clock timestamp (ms since unix epoch). */
+  timestamp: number;
+}
+
 export interface ReactNativePerfStats
   extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
   /**
@@ -78,4 +115,80 @@ export interface ReactNativePerfStats
    * than calling this directly.
    */
   setJsFpsHint(fps: number): void;
+
+  /**
+   * Subscribe to OS-emitted memory pressure events.
+   *
+   * - iOS: `UIApplicationDidReceiveMemoryWarningNotification`, mapped to
+   *   `critical`. Fires on the main thread.
+   * - Android: `ComponentCallbacks2.onTrimMemory` filtered to
+   *   `TRIM_MEMORY_RUNNING_*` (foreground process pressure), plus
+   *   `onLowMemory()` as `critical`. Fires on the main thread.
+   *
+   * The native listener is registered process-wide on first call and
+   * survives `stop()` — memory pressure is independent of the perf
+   * sampler being active. Callbacks are invoked on the JS thread.
+   *
+   * **Always pair this with `removeMemoryWarningListener`** (e.g. in a
+   * React effect cleanup): the callback closure is retained for the life
+   * of the subscription, and forgetting to remove leaks every object the
+   * closure transitively captures — typically the React component instance
+   * that registered it. This matters in dev too: the native listener
+   * table is a process-wide singleton that **does not clear on RN
+   * reload**, so a Fast-Refresh / dev reload that drops the JS realm
+   * without first calling `removeMemoryWarningListener` will leave the
+   * pre-reload callback in the table, pointing at a dead JS context.
+   * The cleanest fix is the same effect-cleanup pattern.
+   *
+   * The relative order in which subscribed callbacks fire for a single
+   * event is **not guaranteed** — iOS iterates a hash dictionary, Android
+   * iterates a LinkedHashMap, and either may change. Don't take a
+   * cross-listener dependency.
+   *
+   * Dispatch: when a warning arrives, the native module walks all
+   * registered callbacks **serially on the main thread** before each
+   * one hops to the JS thread. Cost scales with the number of
+   * subscribers — keep N small (single-digit) and avoid registering one
+   * listener per render-tree branch.
+   *
+   * Side effects of the warning itself (before your callback fires):
+   * - **iOS** runs the same reclaim path as `cleanupNativeCaches`,
+   *   which drops the process-wide `URLCache.shared`, the WK HTTP /
+   *   AppCache / Service-Worker stores, and triggers a libmalloc
+   *   pressure relief. If any code path in the app depends on
+   *   URLCache for offline HTTP content, or on a Service Worker for
+   *   offline WebView fallback, that state is dropped here — don't
+   *   register this listener if either is load-bearing.
+   * - **Android** runs `Runtime.gc()` on every warning (LOW and
+   *   CRITICAL). ART treats it as a hint.
+   *
+   * Returns an opaque id; pass it to `removeMemoryWarningListener` to
+   * unsubscribe.
+   */
+  addMemoryWarningListener(callback: (event: MemoryWarningEvent) => void): number;
+
+  /** Unsubscribe a previously-registered memory warning listener. No-op for unknown ids. */
+  removeMemoryWarningListener(id: number): void;
+
+  /**
+   * Trigger the same native reclaim path the OS memory-warning observer
+   * runs, on demand. Use when the JS layer has reason to believe pressure
+   * is building before the OS posts a warning (e.g. backgrounding, a
+   * heavy route transition, jotai cache invalidation, post-import).
+   *
+   * - **iOS** clears `URLCache.shared` (process-wide HTTP response cache;
+   *   any consumer that relies on URLCache for offline content loses
+   *   it until the next request) and the WK HTTP / AppCache / Service-
+   *   Worker stores (auth-related cookies / localStorage / IndexedDB
+   *   are preserved). Then dispatches `malloc_zone_pressure_relief` on
+   *   a background queue — the call returns to JS immediately, but the
+   *   zone walk that actually frees pages can take 100-500 ms.
+   * - **Android** asks ART to GC via `Runtime.gc()` (hint only; the
+   *   runtime decides whether to honour it). Returns quickly.
+   *
+   * Cheap on Android, cheap-to-return on iOS (heavy work runs async).
+   * Pair with `forceGarbageCollection()` if you also want the JS engine
+   * to participate.
+   */
+  cleanupNativeCaches(): void;
 }