@crumbsdk/react-native 0.0.1-rc.3 → 0.0.1-rc.4

package/README.md

@@ -13,27 +13,124 @@ screenshot masking, diagnostics, durable storage, and upload.
 
 Crumb contains native code and therefore does not run in Expo Go.
 
-## Install
+## Published rc.3 installation
+
+Install the public package and its required Nitro runtime as direct
+dependencies:
 
 ```sh
-yarn add @crumbsdk/react-native react-native-nitro-modules
-cd ios && pod install
+npm install @crumbsdk/react-native@0.0.1-rc.3 \
+  react-native-nitro-modules@0.37.1
 ```
 
-Expo apps should create a development build after installation:
+### Expo
+
+Crumb contains native code and does not run in Expo Go. Add a development
+client and configure the native minimum targets:
+
+```sh
+npx expo install expo-dev-client expo-build-properties
+```
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-build-properties",
+        {
+          "android": { "minSdkVersion": 26 },
+          "ios": { "deploymentTarget": "15.1" }
+        }
+      ]
+    ]
+  }
+}
+```
+
+Create or rebuild the native development client:
 
 ```sh
-npx expo prebuild
 npx expo run:ios
 # or
 npx expo run:android
 ```
 
-No Crumb-specific Expo config plugin is required. React Native autolinking installs
-`CrumbSDKCore` and `CrumbSDKUI` from CocoaPods on iOS and `crumb-ui` from Maven
-Central on Android. The package uses
+No Crumb-specific Expo config plugin is required. Expo Prebuild and React
+Native autolinking install `CrumbSDKCore` and `CrumbSDKUI` from CocoaPods on
+iOS and `crumb-ui` from Maven Central on Android.
+
+### Bare React Native
+
+React Native autolinking discovers Crumb after installation. Install iOS pods,
+then rebuild the applications:
+
+```sh
+npx pod-install
+npm run ios
+# or
+npm run android
+```
+
+No manual `AppDelegate`, `MainApplication`, or package-list registration is
+needed. Set `platform :ios, "15.1"` in a manually maintained Podfile and
+`minSdk = 26` in the Android app module. The package uses
 [`react-native-nitro-modules`](https://nitro.margelo.com/) for its JSI bridge.
 
+The [complete all-platform guide](../../docs/getting-started.md) covers Expo,
+bare React Native, native iOS, and native Android from installation through a
+submitted test report.
+
+## rc.4 candidate installation and migration
+
+This setup applies to **0.0.1-rc.4** and reviewed candidate builds, not rc.3.
+Confirm rc.4 is published before installing it from npm. Until then, the rc.3
+quickstart above remains the published path. Full [candidate release notes](../../docs/releases/0.0.1-rc.4.md) describe the release gates.
+
+After rc.4 publication:
+
+```sh
+npm install @crumbsdk/react-native@0.0.1-rc.4 react-native-nitro-modules@0.37.1
+```
+
+The npm artifact includes Crumb's iOS sources, resource bundles and its pinned
+PLCrashReporter dependency. CocoaPods builds those files locally; new Crumb
+releases do not need publication to the public CocoaPods registry. Other
+libraries in your application may still use that registry.
+
+### Expo development builds
+
+Add `"@crumbsdk/react-native"` to your existing Expo `plugins` array alongside
+`expo-build-properties`. Run a new native prebuild/development build. The plugin
+registers the bundled native dependencies and is safe to run repeatedly.
+Expo Go remains unsupported. Remove old Crumb local-pod plugins or manual
+Crumb pod declarations before enabling this plugin.
+
+### Bare React Native
+
+Inside each application target in `ios/Podfile`, before `use_react_native!`, add:
+
+```ruby
+require File.join(File.dirname(`node --print "require.resolve('@crumbsdk/react-native/package.json')"`.strip), 'scripts', 'ios')
+crumb_native_pods!
+```
+
+Then run `npx pod-install` and rebuild the app. When upgrading from rc.3, remove
+manual `CrumbSDK`, `CrumbSDKCore` and `CrumbSDKUI` declarations first. If CocoaPods
+reports a lockfile source/version conflict, run
+`bundle exec pod update CrumbSDKCore CrumbSDKUI PLCrashReporter --no-repo-update`
+(or `pod update` without Bundler), then review the lockfile changes. Do not
+remove the entire lockfile or update unrelated pods.
+
+If another dependency pins a different PLCrashReporter version, resolve that
+version conflict before installing; do not install two copies or rename the
+framework. The bundled dependency retains its upstream name for CocoaPods to
+check compatibility. Its license and privacy manifest ship with the package.
+
+Native Swift applications should use Swift Package Manager and link both
+`CrumbCore` and `CrumbUI`. Remove CocoaPods' Crumb products before adding the SPM
+products to avoid duplicate modules. SPM does not depend on CocoaPods trunk.
+
 ## Configure
 
 ```ts
@@ -54,6 +151,23 @@ await Crumb.start({
     logs: {
       captureConsole: true,
     },
+    javascriptCrashCapture: {
+      enabled: true,
+      maximumBreadcrumbs: 32,
+      maximumBreadcrumbBytes: 16_384,
+    },
+  },
+  reporter: {
+    theme: 'system',
+    visibleFields: ['category', 'description'],
+  },
+  evidence: ['screenshot', 'performance', 'network', 'logs', 'thread_stacks', 'health_check'],
+  customContext: {
+    values: { account_tier: 'trial' },
+    allowedKeys: ['account_tier'],
+  },
+  workspacePolicy: {
+    url: 'https://policy.example.com/sdk/v1/policy',
   },
 });
 
@@ -73,6 +187,12 @@ const opened = await Crumb.show();
 Shake invocation is enabled by default while the app is foregrounded. Configure
 `invocation: ['programmatic']` to disable it.
 
+Reporter theme, evidence, custom context, and workspace policy use the same
+native-owned contract as Swift and Kotlin. A configured policy fetch is
+non-blocking and fail-closed: optional evidence stays disabled until a fresh or
+valid cached policy is accepted, while the description-only report path
+remains available. See the [shared configuration contract](../../docs/contracts/sdk-configuration.md).
+
 ## JavaScript logs
 
 ```ts
@@ -95,6 +215,68 @@ Crumb.disableConsoleCapture();
 Crumb never captures network bodies, Redux state, navigation history, arbitrary
 application object graphs, or analytics events.
 
+## JavaScript crash capture
+
+JavaScript crash capture is opt-in and disabled by default. Set
+`diagnostics.javascriptCrashCapture.enabled` to `true` to preserve fatal
+JavaScript exceptions and unhandled promise rejections. The adapter performs a
+bounded, sanitized synchronous handoff through Nitro before calling the
+existing React Native or host handler, so Crashlytics, Sentry, and other host
+handlers remain installed and continue to run.
+
+After a relaunch, native code validates and deduplicates the pending record,
+then commits it to the same durable report queue used by the reporter. Offline
+reports remain pending until the normal uploader receives an acknowledgement.
+The record includes the failure type, message, bounded stack, release/bundle
+identity, recent Crumb breadcrumbs, and only custom-context keys explicitly
+allowlisted by the host. It does not include native crash data, arbitrary
+memory, Redux/store state, request bodies, or response bodies.
+
+The native handoff also saves a bounded snapshot of the original process ID,
+capture time, CPU, memory, thread count, thermal state and connectivity when the
+corresponding evidence categories are enabled. These are measurements taken
+while handling the JavaScript failure, not measurements from the next launch.
+iOS reads task/thread counters (at most 256 threads for CPU) and waits at most
+30 ms for a local connectivity observation. Android takes one 20 ms CPU sample
+and reads current process/network metadata. Neither runs continuously, calls
+app-provided log/health callbacks, probes HTTP, captures GPU utilization or
+installs native fatal handlers. With thread-stack evidence enabled, iOS also
+captures bounded native frames using PLCrashReporter's live report API, and
+Android captures managed Java/Kotlin stacks. Native image offsets are not dSYM
+source locations. An unavailable measurement remains unavailable.
+
+Breadcrumbs come from `Crumb.log` and optional console capture. They remain
+bounded and sanitized; disabling logs removes them at handoff and recovery.
+Corrupt or oversized optional snapshot data is discarded without discarding an
+otherwise valid crash. Existing records without snapshots still recover their
+original JavaScript cause and breadcrumbs.
+
+Opt into recent rendering evidence separately with
+`diagnostics.renderingEnabled: true` (default `false`) and install the reporter.
+This enables a foreground-only buffer of five one-second numeric buckets, capped
+at 1,000 observations per bucket, cleared on background or disabled performance
+evidence. The snapshot is frozen before failure stack collection and survives
+relaunch only while current settings still allow it. No frame images are stored.
+
+iOS reports `CADisplayLink` intervals and slow observations. Android reports
+window frame duration and, on API 31+ when supplied by the OS, GPU frame duration.
+Slow observations exceed 1.5 times the relevant frame budget. These are bounded
+observations, not complete frame coverage, FPS, or GPU utilization. iOS GPU time
+remains unavailable. Android zero GPU time is distinct from missing GPU time.
+Envelopes with native stacks or rendering use version 1.1; upgrade the consuming
+service before distributing an enabled SDK. Existing 1.0 reports remain valid.
+
+The breadcrumb limits default to 32 entries and 16 KiB. They can be lowered or
+raised within the package bounds (50 entries and 65,536 bytes maximum). A
+native termination wrapper with the same fingerprint is folded into the
+JavaScript occurrence without replacing its cause.
+
+For a local fatal-fixture check, enable the option in one of the included
+development-build examples and trigger the example's JavaScript failure action.
+The next launch should show one recovered `javascript_crash` occurrence; do not
+enable this option in production without first reviewing the collection notice
+and handler interaction for the host application.
+
 ## Development
 
 This package was created with `create-react-native-library` and includes an Expo
@@ -107,3 +289,83 @@ corepack yarn quality
 corepack yarn example ios
 corepack yarn example android
 ```
+
+## Publishing
+
+Releases publish from the immutable `react-native-v<version>` Git tag through
+the `react-native-npm-publish.yml` GitHub Actions workflow. The workflow uses
+npm trusted publishing (OIDC), so no long-lived npm write token is stored in
+GitHub.
+
+Configure the package's npm trusted publisher with these exact values:
+
+- Provider: GitHub Actions
+- Organization or user: `alexander126`
+- Repository: `crumb`
+- Workflow: `react-native-npm-publish.yml`
+- Environment: leave empty
+- Allowed action: `npm publish`
+
+Use the `next` distribution tag for prereleases and `latest` for stable
+versions. The workflow verifies the package version, immutable Git tag,
+distribution tag, and explicit publication confirmation before it publishes.
+
+### Capture the active screen
+
+Opt in to a static screen label so reports and recovered JavaScript crashes show
+where the user was. This is separate from native controllers and the source file
+identified by a crash stack. Existing reports cannot gain screen context retroactively.
+
+For React Navigation, register once beside the root container. The helper handles
+initial readiness, focused nested routes, modals, subsequent state changes and
+listener cleanup without adding a navigation dependency to Crumb:
+
+```tsx
+import { useEffect } from 'react';
+import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+import Crumb from '@crumbsdk/react-native';
+
+function App() {
+  const navigationRef = useNavigationContainerRef();
+  useEffect(() => Crumb.trackReactNavigation(navigationRef), [navigationRef]);
+  return <NavigationContainer ref={navigationRef}>{/* navigators */}</NavigationContainer>;
+}
+```
+
+For Expo Router, put this in the root layout. `useSegments()` retains file-based
+templates such as `/orders/[id]`; do not pass `usePathname()` or search parameters:
+
+```tsx
+import { Slot, useSegments } from 'expo-router';
+import { useExpoRouterScreen } from '@crumbsdk/react-native';
+
+export default function RootLayout() {
+  useExpoRouterScreen(useSegments());
+  return <Slot />;
+}
+```
+
+For a custom navigator, set the current static label when the visible screen changes:
+
+```ts
+Crumb.setScreen('Checkout', { route: ['Shop', 'Checkout'] });
+Crumb.setScreen(null); // Clear when no app screen is active.
+```
+
+Choose one owner for the current context. Each label is limited to 128 UTF-8 bytes
+and the focused hierarchy to eight labels. Use static names, never user IDs,
+account names, full URLs or search strings. Invalid manual input clears the
+previous label and throws; integrations clear unavailable or invalid state.
+Crumb never reads route parameters or records a navigation history. Standard
+text redaction and the effective `custom_context` evidence policy apply.
+The reporter freezes this context when it opens, including shake invocation;
+a JavaScript failure freezes it at the native handoff. Recovery retains the
+original screen and reapplies current privacy policy, without substituting the
+relaunch screen. This does not identify the cause of a crash or add native fatal
+crash interception.
+
+Screen context uses envelope **1.2**. Deploy a consumer supporting 1.2 before
+shipping an app with this integration. Reports without screen context retain
+their existing 1.0/1.1 format.
+
+Try the [automatic navigation demos](example/NAVIGATION.md) to validate React Navigation and Expo Router on real native builds.

package/android/build.gradle

@@ -32,7 +32,6 @@ def reactNativeArchitectures() {
 apply plugin: "com.android.library"
 apply plugin: "kotlin-android"
 apply from: "../nitrogen/generated/android/crumbsdk_reactnative+autolinking.gradle"
-apply plugin: "com.facebook.react"
 
 def packageJson = new JsonSlurper().parseText(file("../package.json").getText("UTF-8"))
 def crumbNativeVersion = packageJson.crumbNativeVersion

package/android/src/main/java/com/margelo/nitro/crumbsdk/reactnative/CrumbReactNative.kt

@@ -3,20 +3,28 @@ package com.margelo.nitro.crumbsdk.reactnative
 import android.app.Application
 import android.os.Build
 import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.common.LifecycleState
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import dev.crumb.core.Crumb
 import dev.crumb.core.CrumbCaptureOptions
 import dev.crumb.core.CrumbConfiguration
 import dev.crumb.core.CrumbDiagnosticsOptions
+import dev.crumb.core.CrumbEvidenceCategory
 import dev.crumb.core.CrumbInvocation
 import dev.crumb.core.CrumbLogEntry
 import dev.crumb.core.CrumbLogLevel
 import dev.crumb.core.CrumbLogOptions
 import dev.crumb.core.CrumbLogProvider
+import dev.crumb.core.CrumbReporterField
+import dev.crumb.core.CrumbReporterOptions
 import dev.crumb.core.CrumbPrivacyOptions
 import dev.crumb.core.CrumbRelease
+import dev.crumb.core.CrumbTheme
 import dev.crumb.core.CrumbUploadOptions
+import dev.crumb.core.CrumbApplicationMetadata
+import dev.crumb.core.CrumbCustomContextOptions
+import dev.crumb.core.CrumbWorkspacePolicyOptions
 import dev.crumb.ui.CrumbReporter
 import org.json.JSONObject
 
@@ -62,8 +70,12 @@ class CrumbReactNative : HybridCrumbReactNativeSpec() {
                 invocation = payload.invocations(),
                 capture = payload.captureOptions(),
                 diagnostics = CrumbDiagnosticsOptions(
+                    renderingEnabled = diagnostics?.optBoolean("renderingEnabled", false) ?: false,
                     healthCheckUrl = diagnostics?.optionalString("healthCheckUrl"),
                     timeoutMillis = diagnostics?.optionalLong("timeoutMs") ?: 2_000,
+                    javascriptCrashCaptureEnabled = diagnostics
+                        ?.optJSONObject("javascriptCrashCapture")
+                        ?.optionalBoolean("enabled") ?: false,
                     logs = CrumbLogOptions(
                         enabled = logs?.optionalBoolean("enabled") ?: true,
                         lookbackMillis = lookbackMillis,
@@ -77,30 +89,43 @@ class CrumbReactNative : HybridCrumbReactNativeSpec() {
                     ingestionUrl = payload.optJSONObject("upload")
                         ?.optionalString("ingestionUrl"),
                 ),
+                reporter = payload.reporterOptions(),
+                evidence = payload.evidenceOptions(),
+                application = payload.applicationMetadata(),
+                customContext = payload.customContextOptions(),
+                workspacePolicy = payload.workspacePolicyOptions(),
             ),
         )
     }
 
+    override fun setScreenContext(screenJson: String) {
+        Crumb.setScreenContext(screenJson)
+    }
+
+    override fun canCollectLogs(): Boolean = Crumb.canCollectLogs()
+
     override fun installReporter(): Promise<Boolean> {
         val promise = Promise<Boolean>()
         UiThreadUtil.runOnUiThread {
             runCatching {
                 val context = requireNotNull(NitroModules.applicationContext)
                 val application = context.applicationContext as Application
-                CrumbReporter.install(application)
+                val resumedActivity = context.getCurrentActivity()
+                    .takeIf { context.lifecycleState == LifecycleState.RESUMED }
+                CrumbReporter.install(application, resumedActivity)
             }.onSuccess(promise::resolve)
                 .onFailure(promise::reject)
         }
         return promise
     }
 
-    override fun show(): Promise<Boolean> {
+    override fun show(screenJson: String): Promise<Boolean> {
         val promise = Promise<Boolean>()
         UiThreadUtil.runOnUiThread {
             runCatching {
                 val context = requireNotNull(NitroModules.applicationContext)
                 val activity = context.getCurrentActivity() ?: return@runCatching false
-                CrumbReporter.show(activity)
+                CrumbReporter.show(activity, screenContextJSON = screenJson)
             }.onSuccess(promise::resolve)
                 .onFailure(promise::reject)
         }
@@ -108,6 +133,7 @@ class CrumbReactNative : HybridCrumbReactNativeSpec() {
     }
 
     override fun addLog(entryJson: String) {
+        if (!Crumb.canCollectLogs()) return
         val payload = JSONObject(entryJson)
         logBuffer.append(
             CrumbLogEntry(
@@ -123,6 +149,26 @@ class CrumbReactNative : HybridCrumbReactNativeSpec() {
     override fun clearLogs() {
         logBuffer.clear()
     }
+
+    override fun recordJavaScriptCrash(recordJson: String) {
+        val context = NitroModules.applicationContext ?: return
+        Crumb.recordJavaScriptCrash(context, recordJson)
+    }
+
+    override fun recoverJavaScriptCrashes(): Promise<Boolean> {
+        val promise = Promise<Boolean>()
+        val context = NitroModules.applicationContext
+        if (context == null) {
+            promise.resolve(false)
+            return promise
+        }
+        Thread({
+            runCatching { CrumbReporter.recoverJavaScriptCrashes(context) }
+                .onSuccess(promise::resolve)
+                .onFailure { promise.resolve(false) }
+        }, "Crumb JavaScript crash recovery").start()
+        return promise
+    }
 }
 
 private fun JSONObject.invocations(): Set<CrumbInvocation> {
@@ -155,6 +201,78 @@ private fun JSONObject.privacyOptions(): CrumbPrivacyOptions {
     )
 }
 
+private fun JSONObject.reporterOptions(): CrumbReporterOptions {
+    val reporter = optJSONObject("reporter") ?: return CrumbReporterOptions()
+    val theme = when (reporter.optionalString("theme") ?: "system") {
+        "system" -> CrumbTheme.SYSTEM
+        "light" -> CrumbTheme.LIGHT
+        "dark" -> CrumbTheme.DARK
+        else -> error("reporter.theme is unsupported")
+    }
+    val fields = reporter.optJSONArray("visibleFields")?.let { array ->
+        buildSet {
+            for (index in 0 until array.length()) {
+                when (array.getString(index)) {
+                    "category" -> add(CrumbReporterField.CATEGORY)
+                    "description" -> add(CrumbReporterField.DESCRIPTION)
+                    else -> error("reporter.visibleFields contains an unsupported value")
+                }
+            }
+        }
+    } ?: CrumbReporterOptions().visibleFields
+    return CrumbReporterOptions(theme = theme, visibleFields = fields)
+}
+
+private fun JSONObject.evidenceOptions(): Set<CrumbEvidenceCategory> {
+    val evidence = optJSONArray("evidence") ?: return CrumbEvidenceCategory.entries.toSet()
+    return buildSet {
+        for (index in 0 until evidence.length()) {
+            when (evidence.getString(index)) {
+                "screenshot" -> add(CrumbEvidenceCategory.SCREENSHOT)
+                "performance" -> add(CrumbEvidenceCategory.PERFORMANCE)
+                "network" -> add(CrumbEvidenceCategory.NETWORK)
+                "logs" -> add(CrumbEvidenceCategory.LOGS)
+                "thread_stacks" -> add(CrumbEvidenceCategory.THREAD_STACKS)
+                "health_check" -> add(CrumbEvidenceCategory.HEALTH_CHECK)
+                "custom_context" -> add(CrumbEvidenceCategory.CUSTOM_CONTEXT)
+                else -> error("evidence contains an unsupported value")
+            }
+        }
+    }
+}
+
+private fun JSONObject.applicationMetadata(): CrumbApplicationMetadata {
+    val application = optJSONObject("application") ?: return CrumbApplicationMetadata()
+    return CrumbApplicationMetadata(name = application.optionalString("name"))
+}
+
+private fun JSONObject.customContextOptions(): CrumbCustomContextOptions {
+    val customContext = optJSONObject("customContext") ?: return CrumbCustomContextOptions()
+    val values = customContext.optJSONObject("values")?.let { valuesObject ->
+        buildMap {
+            val names = valuesObject.keys()
+            while (names.hasNext()) {
+                val name = names.next()
+                put(name, valuesObject.getString(name))
+            }
+        }
+    } ?: emptyMap()
+    val allowedKeys = customContext.optJSONArray("allowedKeys")?.let { array ->
+        buildSet {
+            for (index in 0 until array.length()) add(array.getString(index))
+        }
+    } ?: emptySet()
+    return CrumbCustomContextOptions(values = values, allowedKeys = allowedKeys)
+}
+
+private fun JSONObject.workspacePolicyOptions(): CrumbWorkspacePolicyOptions {
+    val policy = optJSONObject("workspacePolicy") ?: return CrumbWorkspacePolicyOptions()
+    return CrumbWorkspacePolicyOptions(
+        url = policy.optionalString("url"),
+        timeoutMillis = policy.optionalLong("timeoutMs") ?: 2_000,
+    )
+}
+
 private fun JSONObject.optionalString(name: String): String? =
     if (has(name) && !isNull(name)) getString(name) else null
 

package/app.plugin.js

@@ -0,0 +1,22 @@
+const { configurePodfile } = require('./plugin/podfile.cjs');
+const { name, version } = require('./package.json');
+
+module.exports = function withCrumb(config) {
+  // Resolve Expo from the consuming app, including non-hoisted workspaces.
+  const { withPodfile, createRunOncePlugin } = require(
+    require.resolve('expo/config-plugins', {
+      paths: [config._internal?.projectRoot ?? process.cwd()],
+    })
+  );
+  return createRunOncePlugin(
+    (appConfig) =>
+      withPodfile(appConfig, (modConfig) => {
+        modConfig.modResults.contents = configurePodfile(
+          modConfig.modResults.contents
+        );
+        return modConfig;
+      }),
+    name,
+    version
+  )(config);
+};