@sansavision/apphelm-react-native-profiler 0.0.0-stage → 0.8.1

package/ApphelmReactNativeProfiler.podspec

@@ -0,0 +1,35 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# React Native's version decides which Hermes API the module calls (IHermesRootAPI from 0.81, as
+# Sentry React Native's podspec decides) and whether Hermes is the default engine (0.70 and later).
+rn_package_path = ENV["REACT_NATIVE_NODE_MODULES_DIR"] ? File.join(ENV["REACT_NATIVE_NODE_MODULES_DIR"], "package.json") : `node --print "require.resolve('react-native/package.json')"`.strip
+rn_version = File.exist?(rn_package_path) ? JSON.parse(File.read(rn_package_path))["version"].to_s.split(".").map(&:to_i) : [0, 0]
+rn_major, rn_minor = rn_version[0] || 0, rn_version[1] || 0
+new_hermes_runtime = rn_major >= 1 || (rn_major == 0 && rn_minor >= 81)
+hermes_default = rn_major >= 1 || (rn_major == 0 && rn_minor >= 70)
+using_hermes = (ENV["USE_HERMES"].nil? && hermes_default) || ENV["USE_HERMES"] == "1"
+
+Pod::Spec.new do |s|
+  s.name         = "ApphelmReactNativeProfiler"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://apphelm.dev"
+  s.license      = { :type => "Proprietary", :file => "LICENSE" }
+  s.authors      = "SansaVision"
+  s.platforms    = { :ios => "13.4" }
+  s.source       = { :git => "https://github.com/Sansa-Organisation/apphelm.git", :tag => "v#{s.version}" }
+  s.source_files = "ios/**/*.{h,m,mm}"
+  s.requires_arc = true
+  s.pod_target_xcconfig = {
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    "OTHER_CPLUSPLUSFLAGS" => "$(inherited)" + (new_hermes_runtime ? " -DAPPHELM_NEW_HERMES_RUNTIME" : ""),
+  }
+
+  s.dependency "React-Core"
+  if using_hermes
+    s.dependency "React-hermes"
+    s.dependency "hermes-engine"
+  end
+end

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.8.1 (unreleased)
+
+No code changes; released in lockstep at 0.8.1. The README now says Hermes profile frames are mapped to source through the bundle's uploaded source map (the server already did this).
+
+## 0.8.0 (released 7 Nov 2026)
+
+- First version (for SDK 0.8.0): the native half of `@sansavision/apphelm/react-native-profiling`. An
+  Android module (`HermesSamplingProfiler.enable()`, `disable()`, `dumpSampledTraceToFile()` into the
+  cache directory) and an iOS module (`HermesRuntime::enableSamplingProfiler()` and
+  `dumpSampledTraceToStream()`, or `IHermesRootAPI` from React Native 0.81), as Sentry React Native
+  starts Hermes's sampling profiler. `hermesSampler` is null when the module is not linked. Compiled
+  against stubs of React Native's classes and headers; not yet built in an app or run on a device.

package/LICENSE

@@ -0,0 +1,3 @@
+Copyright 2026 SansaVision. All rights reserved.
+
+This package may be used only under an active Apphelm service agreement. Redistribution, sublicensing, and reverse engineering are prohibited except where applicable law does not permit those restrictions.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @sansavision/apphelm-react-native-profiler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The native half of AppHelm's React Native profiling. It starts and stops Hermes's sampling profiler on Android and iOS, so `@sansavision/apphelm/react-native-profiling` can profile your app's sampled transactions. The rest of the AppHelm React Native SDK has no native code: install this package only if you want profiles.
+
+```sh
+npm install @sansavision/apphelm @sansavision/apphelm-react-native-profiler
+cd ios && pod install
+```
+
+React Native's autolinking picks the module up (Android: `ApphelmHermesProfilerPackage`; iOS: the `ApphelmReactNativeProfiler` pod). Rebuild the app afterwards: a JavaScript reload is not enough.
+
+```ts
+import { Platform } from "react-native";
+import { createReactNativeSdk } from "@sansavision/apphelm/react-native";
+import { hermesProfiling } from "@sansavision/apphelm/react-native-profiling";
+import { hermesSampler } from "@sansavision/apphelm-react-native-profiler";
+
+const apphelm = createReactNativeSdk({
+  apiKey, workspaceId, productId, release: "app@2.3.0+45",
+  tracesSampleRate: 0.2,
+  profiling: hermesProfiling({ profilesSampleRate: 0.5, sampler: hermesSampler, platform: Platform.OS }),
+});
+```
+
+## What it does
+
+- `start()` calls `HermesSamplingProfiler.enable()` (Android) or `HermesRuntime::enableSamplingProfiler()` (iOS; `IHermesRootAPI` from React Native 0.81). Hermes then samples the JavaScript thread about every 10 ms.
+- `stop()` disables the profiler and returns its trace: on Android it is dumped to a file in the app's cache directory, read and deleted; on iOS it is written to memory.
+- When the React instance goes away (a reload, the app closing) a running profiler is disabled.
+- Every failure resolves to `false` or `null`, never an error: the transaction is then sent without a profile.
+
+This is how Sentry React Native profiles Hermes (`RNSentryModuleImpl.startProfiling` on Android, `RNSentryHermesSampler.mm` on iOS). Unlike Sentry, AppHelm doesn't add a native platform profile (Android's method trace, or sentry-cocoa's) to the Hermes profile: the AppHelm Swift and Kotlin SDKs profile native code on their own.
+
+## Limits
+
+- **Hermes only.** On JavaScriptCore `start()` resolves to `false` and nothing is profiled. Expo Go has no custom native modules: use a development build.
+- `hermesSampler` is `null` when the module isn't linked (the app wasn't rebuilt); `hermesProfiling` then does nothing.
+- One profile at a time, at most 30 seconds (the JavaScript side stops it).
+- Release builds name frames by their Hermes bytecode position (`app:///index.android.bundle:1:<offset>`), with minified function names. AppHelm stores those positions and maps them back to your source when the profile is shown, through the bundle's uploaded source map (`apphelm sourcemaps upload --bundle`), naming functions by Metro's function map (`x_facebook_sources`), as it does for errors. A map uploaded after the profile still applies.
+- Not yet built in a React Native app or run on a device by AppHelm: the Java module was compiled against stubs of React Native's classes and the iOS module type-checked against stubs of its headers.
+
+Requires React Native 0.71 or later.

package/android/build.gradle

@@ -0,0 +1,30 @@
+// The Android half of @sansavision/apphelm-react-native-profiler, built by the app's Gradle
+// through React Native's autolinking. HermesSamplingProfiler comes with React Native itself.
+apply plugin: "com.android.library"
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "dev.apphelm.reactnative.profiler"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+  }
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  // Resolved by the React Native Gradle plugin to the app's react-android.
+  implementation "com.facebook.react:react-native:+"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/dev/apphelm/reactnative/profiler/ApphelmHermesProfilerModule.java

@@ -0,0 +1,106 @@
+package dev.apphelm.reactnative.profiler;
+
+import androidx.annotation.NonNull;
+import com.facebook.hermes.instrumentation.HermesSamplingProfiler;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Starts and stops Hermes's sampling profiler for AppHelm's React Native profiling, as Sentry
+ * React Native's RNSentryModuleImpl does: {@code HermesSamplingProfiler.enable()}, then
+ * {@code disable()} and {@code dumpSampledTraceToFile()} into the app's cache directory; the file
+ * is read, returned to JavaScript and deleted. Every failure (JavaScriptCore, an old Hermes, no
+ * cache directory) resolves to false or null: profiling must never break the app.
+ */
+public class ApphelmHermesProfilerModule extends ReactContextBaseJavaModule {
+  public static final String NAME = "ApphelmHermesProfiler";
+  /** A trace larger than this is not read (a 30-second profile is far smaller). */
+  private static final long MAX_TRACE_BYTES = 16L * 1024 * 1024;
+
+  private final Object lock = new Object();
+  private boolean running = false;
+
+  public ApphelmHermesProfilerModule(ReactApplicationContext context) {
+    super(context);
+  }
+
+  @NonNull
+  @Override
+  public String getName() {
+    return NAME;
+  }
+
+  @ReactMethod
+  public void start(Promise promise) {
+    synchronized (lock) {
+      try {
+        // Hermes keeps no state to ask about: clear a profile a previous run left enabled.
+        HermesSamplingProfiler.disable();
+        HermesSamplingProfiler.enable();
+        running = true;
+        promise.resolve(true);
+      } catch (Throwable error) {
+        running = false;
+        promise.resolve(false);
+      }
+    }
+  }
+
+  @ReactMethod
+  public void stop(Promise promise) {
+    File output = null;
+    try {
+      synchronized (lock) {
+        if (!running) {
+          promise.resolve(null);
+          return;
+        }
+        running = false;
+        HermesSamplingProfiler.disable();
+      }
+      output = File.createTempFile("apphelm-hermes-", ".cpuprofile", getReactApplicationContext().getCacheDir());
+      HermesSamplingProfiler.dumpSampledTraceToFile(output.getPath());
+      promise.resolve(read(output));
+    } catch (Throwable error) {
+      promise.resolve(null);
+    } finally {
+      if (output != null) {
+        //noinspection ResultOfMethodCallIgnored
+        output.delete();
+      }
+    }
+  }
+
+  /** The sampler must not outlive the React instance (a reload, the app closing). */
+  @Override
+  public void invalidate() {
+    synchronized (lock) {
+      if (running) {
+        running = false;
+        try {
+          HermesSamplingProfiler.disable();
+        } catch (Throwable ignored) {
+          // Best effort on teardown.
+        }
+      }
+    }
+    super.invalidate();
+  }
+
+  private static String read(File file) throws Exception {
+    if (!file.exists() || file.length() == 0 || file.length() > MAX_TRACE_BYTES) return null;
+    try (InputStream input = new FileInputStream(file); ByteArrayOutputStream bytes = new ByteArrayOutputStream((int) file.length())) {
+      byte[] buffer = new byte[64 * 1024];
+      int read;
+      while ((read = input.read(buffer)) != -1) bytes.write(buffer, 0, read);
+      return new String(bytes.toByteArray(), StandardCharsets.UTF_8);
+    }
+  }
+}

package/android/src/main/java/dev/apphelm/reactnative/profiler/ApphelmHermesProfilerPackage.java

@@ -0,0 +1,24 @@
+package dev.apphelm.reactnative.profiler;
+
+import androidx.annotation.NonNull;
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+import java.util.Collections;
+import java.util.List;
+
+/** Registered by React Native's autolinking. */
+public class ApphelmHermesProfilerPackage implements ReactPackage {
+  @NonNull
+  @Override
+  public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext context) {
+    return Collections.<NativeModule>singletonList(new ApphelmHermesProfilerModule(context));
+  }
+
+  @NonNull
+  @Override
+  public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext context) {
+    return Collections.emptyList();
+  }
+}

package/index.d.ts

@@ -0,0 +1,7 @@
+/** Hermes's sampling profiler, for `hermesProfiling({ sampler })`; null when the native module isn't linked. */
+export declare const hermesSampler: {
+  /** Start Hermes's sampling profiler; false on JavaScriptCore or when it can't start. */
+  start(): Promise<boolean>;
+  /** Stop it and return its trace (Hermes's Chrome trace JSON), or null. */
+  stop(): Promise<string | null>;
+} | null;

package/index.js

@@ -0,0 +1,13 @@
+// The native module (android/ and ios/) as the `sampler` that
+// @sansavision/apphelm/react-native-profiling's `hermesProfiling` takes. When the module isn't
+// linked (Expo Go, a build made before installing this package) it is null and nothing is profiled.
+import { NativeModules } from "react-native";
+
+const native = NativeModules.ApphelmHermesProfiler;
+
+export const hermesSampler = native && typeof native.start === "function" && typeof native.stop === "function"
+  ? {
+      start: () => native.start().then((started) => started === true, () => false),
+      stop: () => native.stop().then((trace) => (typeof trace === "string" && trace.length > 0 ? trace : null), () => null),
+    }
+  : null;

package/ios/ApphelmHermesProfiler.mm

@@ -0,0 +1,127 @@
+// The iOS half of @sansavision/apphelm-react-native-profiler: starts and stops Hermes's sampling
+// profiler for AppHelm's React Native profiling, as Sentry React Native's RNSentryHermesSampler.mm
+// does (HermesRuntime::enableSamplingProfiler / disableSamplingProfiler /
+// dumpSampledTraceToStream; the IHermesRootAPI form from React Native 0.81). Without Hermes
+// (JavaScriptCore) `start` resolves to NO and nothing is profiled. No call ever rejects.
+
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+#import <mutex>
+#import <sstream>
+#import <string>
+
+#if __has_include(<hermes/hermes.h>)
+#  define APPHELM_HERMES_SAMPLER 1
+#  import <hermes/hermes.h>
+#else
+#  define APPHELM_HERMES_SAMPLER 0
+#endif
+
+namespace {
+#if APPHELM_HERMES_SAMPLER
+std::mutex samplerMutex;
+bool running = false;
+
+void enableSampler()
+{
+#  ifdef APPHELM_NEW_HERMES_RUNTIME
+  auto *api = facebook::jsi::castInterface<facebook::hermes::IHermesRootAPI>(facebook::hermes::makeHermesRootAPI());
+  if (api) api->enableSamplingProfiler();
+#  else
+  facebook::hermes::HermesRuntime::enableSamplingProfiler();
+#  endif
+}
+
+void disableSampler()
+{
+#  ifdef APPHELM_NEW_HERMES_RUNTIME
+  auto *api = facebook::jsi::castInterface<facebook::hermes::IHermesRootAPI>(facebook::hermes::makeHermesRootAPI());
+  if (api) api->disableSamplingProfiler();
+#  else
+  facebook::hermes::HermesRuntime::disableSamplingProfiler();
+#  endif
+}
+
+std::string dumpTrace()
+{
+  std::stringstream stream;
+#  ifdef APPHELM_NEW_HERMES_RUNTIME
+  auto *api = facebook::jsi::castInterface<facebook::hermes::IHermesRootAPI>(facebook::hermes::makeHermesRootAPI());
+  if (api) api->dumpSampledTraceToStream(stream);
+#  else
+  facebook::hermes::HermesRuntime::dumpSampledTraceToStream(stream);
+#  endif
+  return stream.str();
+}
+#endif
+} // namespace
+
+@interface ApphelmHermesProfiler : NSObject <RCTBridgeModule>
+@end
+
+@implementation ApphelmHermesProfiler
+
+RCT_EXPORT_MODULE(ApphelmHermesProfiler)
+
++ (BOOL)requiresMainQueueSetup
+{
+  return NO;
+}
+
+RCT_EXPORT_METHOD(start : (RCTPromiseResolveBlock)resolve reject : (__unused RCTPromiseRejectBlock)reject)
+{
+#if APPHELM_HERMES_SAMPLER
+  std::lock_guard<std::mutex> lock(samplerMutex);
+  try {
+    // Hermes keeps no state to ask about: clear a profile a previous run left enabled.
+    disableSampler();
+    enableSampler();
+    running = true;
+    resolve(@YES);
+  } catch (...) {
+    running = false;
+    resolve(@NO);
+  }
+#else
+  resolve(@NO);
+#endif
+}
+
+RCT_EXPORT_METHOD(stop : (RCTPromiseResolveBlock)resolve reject : (__unused RCTPromiseRejectBlock)reject)
+{
+#if APPHELM_HERMES_SAMPLER
+  std::lock_guard<std::mutex> lock(samplerMutex);
+  if (!running) {
+    resolve([NSNull null]);
+    return;
+  }
+  running = false;
+  try {
+    disableSampler();
+    std::string trace = dumpTrace();
+    NSString *text = trace.empty() ? nil : [[NSString alloc] initWithBytes:trace.data() length:trace.size() encoding:NSUTF8StringEncoding];
+    resolve(text ?: (id)[NSNull null]);
+  } catch (...) {
+    resolve([NSNull null]);
+  }
+#else
+  resolve([NSNull null]);
+#endif
+}
+
+// The sampler must not outlive the React instance (a reload, the app closing).
+- (void)invalidate
+{
+#if APPHELM_HERMES_SAMPLER
+  std::lock_guard<std::mutex> lock(samplerMutex);
+  if (running) {
+    running = false;
+    try {
+      disableSampler();
+    } catch (...) {
+    }
+  }
+#endif
+}
+
+@end

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@sansavision/apphelm-react-native-profiler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "The native half of AppHelm's React Native profiling: starts and stops Hermes's sampling profiler (Android and iOS) for @sansavision/apphelm/react-native-profiling.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./index.js" }
+  },
+  "files": ["index.js", "index.d.ts", "ApphelmReactNativeProfiler.podspec", "ios", "android/build.gradle", "android/src", "README.md", "CHANGELOG.md", "LICENSE"],
+  "peerDependencies": { "react-native": ">=0.71" },
+  "peerDependenciesMeta": { "react-native": { "optional": true } },
+  "publishConfig": { "access": "public", "provenance": false }
+}