@react-native-firebase/perf 26.3.3 → 27.0.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [27.0.0](https://github.com/invertase/react-native-firebase/compare/v26.4.0...v27.0.0) (2026-10-19)
+
+### ⚠ BREAKING CHANGES
+
+- **app, sdk:** bump Firebase Android 35, Apple 13, and JS 13
+
+### Features
+
+- **app, sdk:** bump Firebase Android 35, Apple 13, and JS 13 ([0ca03d1](https://github.com/invertase/react-native-firebase/commit/0ca03d11b0c271fb37cfbee8a0c3074a21969f0b))
+
+### Bug Fixes
+
+- **perf, ios:** avoid id cast shadowed by TurboModule id param ([9556118](https://github.com/invertase/react-native-firebase/commit/955611850796e2589c0286ab4700a4eb6ec5d2a3))
+- **perf, ios:** typedef Swift protocol refs around TurboModule id shadowing ([db9cc60](https://github.com/invertase/react-native-firebase/commit/db9cc60e6eb2eb4331702393e2649f102b7cce70))
+- **perf, ios:** use id casts for Swift protocols in ObjC++ ([1d5c7ca](https://github.com/invertase/react-native-firebase/commit/1d5c7ca28d674d7c3bdd19d085911abccda2b20e))
+
+## [26.4.0](https://github.com/invertase/react-native-firebase/compare/v26.3.3...v26.4.0) (2026-09-05)
+
+### Bug Fixes
+
+- **perf, android:** use RNFBHandleMap for traces and http metrics ([60b6e7d](https://github.com/invertase/react-native-firebase/commit/60b6e7daa005d137228763291be0db75997b9162))
+
 ## [26.3.3](https://github.com/invertase/react-native-firebase/compare/v26.3.2...v26.3.3) (2026-09-01)
 
 ### Bug Fixes

package/RNFBPerf.podspec

@@ -29,16 +29,21 @@ Pod::Spec.new do |s|
   s.ios.deployment_target = firebase_ios_target
   s.macos.deployment_target = firebase_macos_target
   s.tvos.deployment_target = firebase_tvos_target
+  s.swift_version       = '5.10'
   s.source_files        = 'ios/**/*.{h,m,mm,cpp,swift}'
   s.private_header_files = "ios/**/*.h"
-  s.exclude_files       = 'ios/generated/RCTThirdPartyComponentsProvider.*', 'ios/generated/RCTAppDependencyProvider.*', 'ios/generated/RCTModuleProviders.*', 'ios/generated/RCTModulesConformingToProtocolsProvider.*', 'ios/generated/RCTUnstableModulesRequiringMainQueueSetupProvider.*'
+  # CocoaPods FileList uses FNM_PATHNAME: `ios/*UnitTests/**` does not match nested
+  # paths like `ios/RNFBPerfUnitTests/HostStubs/**` (those would compile into the pod).
+  s.exclude_files       = 'ios/generated/RCTThirdPartyComponentsProvider.*', 'ios/generated/RCTAppDependencyProvider.*', 'ios/generated/RCTModuleProviders.*', 'ios/generated/RCTModulesConformingToProtocolsProvider.*', 'ios/generated/RCTUnstableModulesRequiringMainQueueSetupProvider.*', 'ios/*UnitTests/**/*'
 
   # Must be set before install_modules_dependencies so RN can append use_frameworks
   # HEADER_SEARCH_PATHS (React-debug etc.). Assigning after overwrites those paths
   # and breaks from-source builds: react/timing/primitives.h → react/debug/flags.h.
   # CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES is required so the
   # framework module validates when consumers build with use_frameworks!.
+  # DEFINES_MODULE is required for the generated RNFBPerf-Swift.h interface.
   s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
     "CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES" => "YES",
   }
 

package/android/build.gradle

@@ -15,6 +15,7 @@ buildscript {
 
     dependencies {
       classpath("com.android.tools.build:gradle:8.4.0")
+      classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${project.findProperty('kotlinVersion') ?: '2.4.0'}")
     }
   }
 }
@@ -23,6 +24,8 @@ plugins {
   id "io.invertase.gradle.build" version "1.5"
 }
 
+apply plugin: "org.jetbrains.kotlin.android"
+
 def appProject
 if (findProject(':@react-native-firebase_app')) {
   appProject = project(':@react-native-firebase_app')
@@ -135,6 +138,8 @@ dependencies {
   api appProject
   implementation platform("com.google.firebase:firebase-bom:${ReactNative.ext.getVersion("firebase", "bom")}")
   implementation "com.google.firebase:firebase-perf"
+
+  testImplementation "junit:junit:4.13.2"
 }
 
 ReactNative.shared.applyPackageVersion()

package/android/src/main/java/io/invertase/firebase/perf/RNFBPerfHandleRegistry.kt

@@ -0,0 +1,71 @@
+package io.invertase.firebase.perf
+
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import io.invertase.firebase.common.RNFBHandleCollisionException
+import io.invertase.firebase.common.RNFBHandleMap
+import java.util.function.Predicate
+
+/**
+ * Perf id → metric handle map (traces, screen traces, HTTP metrics). Module start paths use
+ * [putReplacing] (last wins, stop displaced outside lock). Unique [put] / [putOrDiscard] remain for
+ * tests. Callers [get] then [take] then stop outside the HandleMap lock. Tear-down discards via
+ * [takeAll] without stopping (matches prior SparseArray clear).
+ */
+internal class RNFBPerfHandleRegistry<V> {
+  private val map = RNFBHandleMap<Int, V>()
+
+  @Throws(RNFBHandleCollisionException::class)
+  fun put(
+    id: Int,
+    handle: V,
+  ) {
+    map.put(id, handle)
+  }
+
+  /**
+   * Unique put. On collision, drop the incoming handle without stopping and leave the existing
+   * mapping.
+   *
+   * @return true if stored
+   */
+  fun putOrDiscard(
+    id: Int,
+    handle: V,
+  ): Boolean = map.putIfAbsent(id, handle)
+
+  /**
+   * Atomically replaces the mapping for [id] (last wins). Returns the displaced handle, or `null`
+   * if the id was free. Stop the displaced handle after this method returns.
+   */
+  fun putReplacing(
+    id: Int,
+    handle: V,
+  ): V? = map.putReplacing(id, handle)
+
+  fun get(id: Int): V? = map.get(id)
+
+  fun take(id: Int): V? = map.take(id)
+
+  fun takeIf(
+    id: Int,
+    shouldTake: Predicate<V>,
+  ): V? = map.takeIf(id, shouldTake)
+
+  fun takeAll(): List<V> = map.takeAll()
+}

package/android/src/main/java/io/invertase/firebase/perf/UniversalFirebasePerfModule.java

@@ -20,7 +20,6 @@ package io.invertase.firebase.perf;
 import android.app.Activity;
 import android.content.Context;
 import android.os.Bundle;
-import android.util.SparseArray;
 import com.google.android.gms.tasks.Task;
 import com.google.android.gms.tasks.Tasks;
 import com.google.firebase.perf.FirebasePerformance;
@@ -33,9 +32,11 @@ import java.util.Objects;
 import java.util.Set;
 
 public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
-  private static SparseArray<Trace> traces = new SparseArray<>();
-  private static SparseArray<ScreenTrace> screenTraces = new SparseArray<>();
-  private static SparseArray<HttpMetric> httpMetrics = new SparseArray<>();
+  private static final RNFBPerfHandleRegistry<Trace> traces = new RNFBPerfHandleRegistry<>();
+  private static final RNFBPerfHandleRegistry<ScreenTrace> screenTraces =
+      new RNFBPerfHandleRegistry<>();
+  private static final RNFBPerfHandleRegistry<HttpMetric> httpMetrics =
+      new RNFBPerfHandleRegistry<>();
 
   UniversalFirebasePerfModule(Context context, String serviceName) {
     super(context, serviceName);
@@ -44,9 +45,10 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
   @Override
   public void onTearDown() {
     super.onTearDown();
-    traces.clear();
-    httpMetrics.clear();
-    screenTraces.clear();
+    // Drop mappings only — matches prior SparseArray.clear() (no stop/cancel).
+    traces.takeAll();
+    httpMetrics.takeAll();
+    screenTraces.takeAll();
   }
 
   @Override
@@ -72,9 +74,7 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
         () -> {
           Trace trace = FirebasePerformance.getInstance().newTrace(identifier);
           trace.start();
-
-          traces.put(id, trace);
-
+          registerStartedTrace(id, trace);
           return null;
         });
   }
@@ -101,8 +101,10 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
                 attributeKey, (String) Objects.requireNonNull(attributes.get(attributeKey)));
           }
 
-          trace.stop();
-          traces.remove(id);
+          Trace taken = traces.takeIf(id, t -> t == trace);
+          if (taken != null) {
+            taken.stop();
+          }
 
           return null;
         });
@@ -113,8 +115,7 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
         () -> {
           ScreenTrace screenTrace = new ScreenTrace(activity, identifier);
           screenTrace.recordScreenTrace();
-          screenTraces.put(id, screenTrace);
-
+          registerRecordedScreenTrace(id, screenTrace);
           return null;
         });
   }
@@ -127,8 +128,11 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
           if (trace == null) {
             return null;
           }
-          trace.sendScreenTrace();
-          screenTraces.remove(id);
+
+          ScreenTrace taken = screenTraces.takeIf(id, t -> t == trace);
+          if (taken != null) {
+            taken.sendScreenTrace();
+          }
 
           return null;
         });
@@ -139,7 +143,7 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
         () -> {
           HttpMetric httpMetric = FirebasePerformance.getInstance().newHttpMetric(url, httpMethod);
           httpMetric.start();
-          httpMetrics.put(id, httpMetric);
+          registerStartedHttpMetric(id, httpMetric);
           return null;
         });
   }
@@ -178,8 +182,10 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
                 attributeKey, Objects.requireNonNull(attributes.getString(attributeKey)));
           }
 
-          httpMetric.stop();
-          httpMetrics.remove(id);
+          HttpMetric taken = httpMetrics.takeIf(id, m -> m == httpMetric);
+          if (taken != null) {
+            taken.stop();
+          }
 
           return null;
         });
@@ -190,7 +196,7 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
   void startTraceSync(int id, String identifier) {
     Trace trace = FirebasePerformance.getInstance().newTrace(identifier);
     trace.start();
-    traces.put(id, trace);
+    registerStartedTrace(id, trace);
   }
 
   void stopTraceSync(int id, Bundle metrics, Bundle attributes) {
@@ -213,14 +219,16 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
           attributeKey, (String) Objects.requireNonNull(attributes.get(attributeKey)));
     }
 
-    trace.stop();
-    traces.remove(id);
+    Trace taken = traces.takeIf(id, t -> t == trace);
+    if (taken != null) {
+      taken.stop();
+    }
   }
 
   void startScreenTraceSync(Activity activity, int id, String identifier) {
     ScreenTrace screenTrace = new ScreenTrace(activity, identifier);
     screenTrace.recordScreenTrace();
-    screenTraces.put(id, screenTrace);
+    registerRecordedScreenTrace(id, screenTrace);
   }
 
   void stopScreenTraceSync(int id) {
@@ -229,14 +237,17 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
     if (trace == null) {
       return;
     }
-    trace.sendScreenTrace();
-    screenTraces.remove(id);
+
+    ScreenTrace taken = screenTraces.takeIf(id, t -> t == trace);
+    if (taken != null) {
+      taken.sendScreenTrace();
+    }
   }
 
   void startHttpMetricSync(int id, String url, String httpMethod) {
     HttpMetric httpMetric = FirebasePerformance.getInstance().newHttpMetric(url, httpMethod);
     httpMetric.start();
-    httpMetrics.put(id, httpMetric);
+    registerStartedHttpMetric(id, httpMetric);
   }
 
   void stopHttpMetricSync(int id, Bundle httpMetricConfig, Bundle attributes) {
@@ -269,7 +280,33 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
           attributeKey, Objects.requireNonNull(attributes.getString(attributeKey)));
     }
 
-    httpMetric.stop();
-    httpMetrics.remove(id);
+    HttpMetric taken = httpMetrics.takeIf(id, m -> m == httpMetric);
+    if (taken != null) {
+      taken.stop();
+    }
+  }
+
+  /** Last-wins registration: stop any displaced trace outside the HandleMap lock. */
+  private static void registerStartedTrace(int id, Trace trace) {
+    Trace displaced = traces.putReplacing(id, trace);
+    if (displaced != null) {
+      displaced.stop();
+    }
+  }
+
+  /** Last-wins registration: stop any displaced HTTP metric outside the HandleMap lock. */
+  private static void registerStartedHttpMetric(int id, HttpMetric httpMetric) {
+    HttpMetric displaced = httpMetrics.putReplacing(id, httpMetric);
+    if (displaced != null) {
+      displaced.stop();
+    }
+  }
+
+  /** Last-wins registration: finalize any displaced screen trace outside the HandleMap lock. */
+  private static void registerRecordedScreenTrace(int id, ScreenTrace screenTrace) {
+    ScreenTrace displaced = screenTraces.putReplacing(id, screenTrace);
+    if (displaced != null) {
+      displaced.sendScreenTrace();
+    }
   }
 }

package/android/src/test/java/io/invertase/firebase/perf/RNFBPerfHandleRegistryTest.java

@@ -0,0 +1,205 @@
+package io.invertase.firebase.perf;
+
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+import io.invertase.firebase.common.RNFBHandleCollisionException;
+import java.util.List;
+import org.junit.Test;
+
+/**
+ * JVM coverage for {@link RNFBPerfHandleRegistry}. Does not instantiate {@code
+ * UniversalFirebasePerfModule} / Firebase Perf types — D12.
+ */
+public class RNFBPerfHandleRegistryTest {
+
+  @Test
+  public void putTake_happyPath() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "trace");
+    assertSame("trace", registry.take(1));
+    assertNull(registry.take(1));
+  }
+
+  @Test
+  public void put_occupiedId_throwsCollision() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "first");
+    try {
+      registry.put(1, "second");
+      fail("expected RNFBHandleCollisionException");
+    } catch (RNFBHandleCollisionException e) {
+      assertTrue(e.getMessage().contains("1"));
+      assertSame("first", registry.take(1));
+    }
+  }
+
+  @Test
+  public void take_whenFree_isNull() {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    assertNull(registry.take(99));
+  }
+
+  @Test
+  public void putOrDiscard_storesWhenFree() {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    assertTrue(registry.putOrDiscard(1, "trace"));
+    assertSame("trace", registry.take(1));
+  }
+
+  @Test
+  public void putOrDiscard_collision_dropsIncomingWithoutDiscard() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "first");
+    assertFalse(registry.putOrDiscard(1, "second"));
+    assertSame("first", registry.take(1));
+  }
+
+  @Test
+  public void putOrDiscard_collision_nullIncoming_isNoOp() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "first");
+    assertFalse(registry.putOrDiscard(1, null));
+    assertSame("first", registry.take(1));
+  }
+
+  @Test
+  public void putReplacing_whenFree_stores() {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    assertNull(registry.putReplacing(1, "trace"));
+    assertSame("trace", registry.get(1));
+  }
+
+  @Test
+  public void putReplacing_whenOccupied_returnsDisplaced() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "first");
+    assertSame("first", registry.putReplacing(1, "second"));
+    assertSame("second", registry.get(1));
+  }
+
+  @Test
+  public void putReplacing_moduleCollisionPattern_stopsDisplacedOutsideLock() throws Exception {
+    RNFBPerfHandleRegistry<FakeStoppableHandle> registry = new RNFBPerfHandleRegistry<>();
+    FakeStoppableHandle first = new FakeStoppableHandle();
+    FakeStoppableHandle second = new FakeStoppableHandle();
+    registry.put(1, first);
+    FakeStoppableHandle displaced = registry.putReplacing(1, second);
+    if (displaced != null) {
+      displaced.stop();
+    }
+    assertEquals(1, first.stopCount);
+    assertEquals(0, second.stopCount);
+    assertSame(second, registry.get(1));
+  }
+
+  @Test
+  public void takeIf_whenMissing_returnsNullWithoutCallingPredicate() {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    boolean[] called = {false};
+    assertNull(
+        registry.takeIf(
+            99,
+            value -> {
+              called[0] = true;
+              return true;
+            }));
+    assertFalse(called[0]);
+  }
+
+  @Test
+  public void takeIf_whenPredicateFalse_leavesMapping() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "trace");
+    assertNull(registry.takeIf(1, value -> false));
+    assertSame("trace", registry.get(1));
+  }
+
+  @Test
+  public void takeIf_whenPredicateTrue_removesAndReturns() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "trace");
+    assertSame("trace", registry.takeIf(1, value -> value == "trace"));
+    assertNull(registry.get(1));
+  }
+
+  @Test
+  public void get_whenFree_isNull() {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    assertNull(registry.get(99));
+  }
+
+  @Test
+  public void get_whenOccupied_returnsHandle() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "trace");
+    assertSame("trace", registry.get(1));
+    assertSame("trace", registry.take(1));
+  }
+
+  @Test
+  public void takeAll_returnsSnapshotAndLeavesEmpty() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "a");
+    registry.put(2, "b");
+    List<String> remaining = registry.takeAll();
+    assertEquals(2, remaining.size());
+    assertTrue(remaining.contains("a"));
+    assertTrue(remaining.contains("b"));
+    assertNull(registry.take(1));
+    assertNull(registry.take(2));
+  }
+
+  @Test
+  public void takeAll_empty_returnsEmptyList() {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    assertTrue(registry.takeAll().isEmpty());
+  }
+
+  @Test
+  public void takeAll_nullHandle_isIncluded() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, null);
+    List<String> remaining = registry.takeAll();
+    assertEquals(1, remaining.size());
+    assertNull(remaining.get(0));
+  }
+
+  @Test
+  public void put_afterTake_allowsReuse() throws Exception {
+    RNFBPerfHandleRegistry<String> registry = new RNFBPerfHandleRegistry<>();
+    registry.put(1, "first");
+    assertSame("first", registry.take(1));
+    registry.put(1, "second");
+    assertSame("second", registry.take(1));
+  }
+
+  private static final class FakeStoppableHandle {
+    int stopCount = 0;
+
+    void stop() {
+      stopCount++;
+    }
+  }
+}

package/dist/module/version.js

@@ -1,5 +1,5 @@
 "use strict";
 
 // Generated by genversion.
-export const version = '26.3.3';
+export const version = '27.0.0';
 //# sourceMappingURL=version.js.map

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

@@ -1,7 +1,7 @@
 import type { FirebaseApp } from '@react-native-firebase/app';
 import './types/internal';
 import type { FirebasePerformance, HttpMetric, HttpMethod, PerformanceSettings, PerformanceTrace, ScreenTrace } from './types/perf';
-export declare const SDK_VERSION = "26.3.3";
+export declare const SDK_VERSION = "27.0.0";
 export declare function getPerformance(app?: FirebaseApp): FirebasePerformance;
 /**
  * Creates a Performance Monitoring instance and applies optional settings.

package/dist/typescript/lib/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "26.3.3";
+export declare const version = "27.0.0";
 //# sourceMappingURL=version.d.ts.map

package/ios/RNFBPerf/RNFBPerfHandleRegistry.h

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Perf trace / HTTP metric handle map. Module start paths use `putReplacing` (last wins, stop
+ * displaced outside lock). Unique `put` / `putOrDiscard` remain for tests. Callers `get` then
+ * `take` then stop outside the HandleMap lock. Tear-down uses `takeAll` without stopping.
+ */
+@interface RNFBPerfHandleRegistry : NSObject
+
+- (BOOL)put:(id)key value:(id)value error:(NSError *_Nullable *_Nullable)error;
+/// Unique put. On collision, drop the incoming handle without stopping.
+- (BOOL)putOrDiscard:(id)key value:(id)value;
+/// Last wins. Returns the displaced handle, or nil if the key was free.
+- (nullable id)putReplacing:(id)key value:(id)value;
+- (nullable id)get:(id)key;
+- (nullable id)take:(id)key;
+- (nullable id)takeIf:(id)key when:(BOOL (^)(id value))condition;
+- (NSArray *)takeAll;
+
+@end
+
+NS_ASSUME_NONNULL_END