@everframe/react-native 1.0.0 → 1.2.0

package/EverframeRN.podspec

@@ -35,8 +35,12 @@ package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
 # evaluated from inside the published npm tarball at a consumer's install, where
 # no workspace path exists. Unset — every consumer install — the derivation
 # below is the only source of truth, unchanged.
+#
+# The bridge calls `EverframeConfig(sdkKey:)`, which first ships in native
+# 1.2.0, so the range already asks for 1.2 while package.json is still 1.1.0.
+# The 1.2.0 release moves package.json to match.
 native_version_override = ENV['EVERFRAME_NATIVE_POD_VERSION'].to_s.strip
-native_minor_range = native_version_override.empty? ? '~> 1.0.0' : native_version_override
+native_minor_range = native_version_override.empty? ? '~> 1.2.0' : native_version_override
 
 Pod::Spec.new do |s|
   s.name         = 'EverframeRN'

package/README.md

@@ -11,6 +11,9 @@ modal to RN host apps via a TurboModule + a thin React provider/hook API.
 
 ---
 
+See the [crash-reporting support matrix](../../docs/crash-reporting-support.md)
+for exact tested paths, unsupported combinations and remaining qualification.
+
 ## Installation
 
 ```bash
@@ -56,11 +59,11 @@ import { EverframeProvider, useEverframe } from '@everframe/react-native';
 
 export default function App() {
   return (
-    // `apiKey` is the only required field. The ingest endpoint is a
+    // `sdkKey` is the only required field. The ingest endpoint is a
     // compile-time constant in the SDK and is not configurable in v1.
     <EverframeProvider
       config={{
-        apiKey: 'txx_live_xxxxxxxxxxxxxxxx',
+        sdkKey: 'evf_live_xxxxxxxxxxxxxxxx',
         // Recommended in RN/Expo development: shake also opens the dev menu.
         shakeToReport: { enabled: !__DEV__ },
       }}
@@ -96,10 +99,259 @@ provider context and attach any non-sensitive context needed for diagnosis.
 The source API requires matching rebuilt native components; published `0.7.0`
 artifacts are not evidence of support.
 
+## Release health
+
+Release health counts crash-free foreground sessions for each version of your
+app. It is on by default, and debug builds of the native app aren't counted.
+Turn it off in the `EverframeProvider` config:
+
+```tsx
+releaseHealth: { enabled: false },
+```
+
+Sessions come from the Android and iOS SDKs and count toward the native app
+version, which an over-the-air update doesn't change. Release health needs the
+Hermes bundle identity that `@everframe/metro` adds at build time (or the
+`jsBundle` option); without it, release health stays off and the SDK logs an
+`[everframe]` warning (in development builds only, unless you set
+`releaseHealth`). Add `userId: accountId` to count crash-free users, and
+`includeDebugBuilds: true` to count debug builds too. The configuration is read
+when the Provider mounts, so remount it with a changed `key` to change `enabled`
+or `userId`. A configure with `enabled: false` turns release health off and
+erases its queued records on the device.
+Release health skips a debug build, which is `__DEV__` unless you set
+`debugBuild` on the Provider. See
+[release health](../../docs/release-health.md).
+
+## Promise rejection observation
+
+Automatic Hermes rejection observation is opt-in:
+
+```tsx
+import { EverframeProvider, getPromiseRejectionStatus } from '@everframe/react-native';
+
+<EverframeProvider config={{
+  sdkKey: '…',
+  crashReporting: { promiseRejections: { enabled: true } },
+}}>
+  <App />
+</EverframeProvider>
+
+// Read after mount. This reports observer coverage, not delivery confirmation.
+const status = getPromiseRejectionStatus();
+```
+
+The verified runtime is Android/iOS `react-native-tvos@0.85.3-0` with Hermes
+release `250829098.0.10`, Release/Static Hermes and bytecode 98. Qualification
+uses optimized apps on an Android API 35 arm64 emulator and an iOS 26.5 arm64
+simulator with Debug/local native SDK transport, including expiry after the app
+process is suspended, source mapping and encrypted retry after relaunch.
+Physical devices, device sleep and production transport are not qualified by
+these checks. Matching the SDK's broader RN peer range does not establish
+rejection support. Other versions, JSC, browser execution, tvOS,
+unverified Promise replacements and incompatible hooks return `unsupported`.
+The adapter checks runtime identity and a fulfilled-only hook handshake; it
+does not generate a test rejection or replace the Promise constructor.
+
+Rejections still unhandled after 2 seconds enter the existing nonfatal capture
+path. A handler attached within that interval cancels capture; later handling
+does not retract an accepted report. The notification uses a JavaScript timer.
+Android pauses JavaScript timers while the app's activity is paused (in the
+background, behind another activity or in picture-in-picture), although
+JavaScript can keep running. Rejections observed then are notified on later
+Promise activity or when the activity resumes. Explicit capture and automatic
+reporting share accepted error identity, and automatic reports retain their
+existing 10-distinct-key allowance per mount. Automatic reports are
+deduplicated by exception type and top stack frame. Non-Error reasons have no
+stack and are deduplicated by their reported value with digit runs ignored, so
+`Request 1001 failed` repeats `Request 1000 failed` and all object reasons
+share one report per mount. They spend at most 5 of the 10 keys, so values that
+differ in other ways, such as hex identifiers, still leave 5 keys for `Error`
+rejections and other automatic reports.
+
+The observer retains at most 16 detached snapshots, each at most 64 KiB of
+serialized UTF-8 data. It drops new arrivals when full and oversize snapshots
+rather than retaining arbitrary error graphs. Work is counted as expired
+instead of reported when it is notified more than 30 seconds after the
+rejection. Age is measured on the platform's elapsed clock and bounded by
+wall-clock time, which keeps advancing while an Android device sleeps. Cleanup
+cannot run while JavaScript is suspended, so stale work expires when
+JavaScript resumes. Error facts and causes are snapshotted at rejection time.
+Rejection reasons that are not `Error` objects are reported as `UnhandledValue`
+without a stack or cause chain, even when they carry a `cause`. Strings,
+numbers, booleans, `null` and `undefined` keep their bounded value; objects,
+arrays, functions, symbols and bigints are reported only as a type label such
+as `[object]` rather than serialized.
+Native context and breadcrumbs are collected at notification time. A preserved
+external tracker may independently retain errors or generate its own reports.
+
+`getPromiseRejectionStatus()` returns `disabled`, `unsupported`, `observing`,
+`displaced`, `install-failed`, or `not-mounted`, with a reason and bounded
+counters for pending, accepted, cancelled, dropped, expired, suppressed,
+refused, failed and discarded captures. A rejection handled within the 2-second interval counts as cancelled,
+even if it was dropped or failed to snapshot on arrival. Counters saturate at
+2,147,483,647 and reset on each mount; they contain no captured messages or
+stacks. Replacing either hook stops this observer until a new mount and
+releases its pending work, counted as `discarded`.
+`crashReporting.disabled: true` overrides the opt-in, and unmount discards
+pending work. Configuration changes take effect on a new mount.
+The browser export reports Hermes observation as unsupported and preserves the
+browser SDK's own error handling.
+
+## Error capture and diagnostics
+
+### Native crashes and ANRs
+
+Crash reporting also turns on the native SDKs' automatic crash capture. On Android that covers JVM exceptions, native crashes (OS exit records on API 30+, with tombstone frames on API 31+) and ANRs on API 30+; see the [Android SDK guide](../sdk-android/README.md#crash-capture-on-by-default). On iOS it is the native crash recorder. `crashReporting: { disabled: true }` turns all of it off on both platforms.
+
+### Errors no boundary catches
+
+Since React Native 0.78, React reports an error that no error boundary catches
+(thrown while rendering, in an effect or in a lifecycle method) through the
+root's `onUncaughtError`. That calls React Native's `ExceptionsManager`, never
+the `ErrorUtils` handler. Crash reporting hooks
+`ExceptionsManager.handleException` too, so such an error is reported as a fatal
+JavaScript crash (`mechanism: "errorutils"`) with its Hermes stack, and React's
+component stack follows the message after `This error is located at:`, as in
+React Native's own report. React unmounts the whole tree, `EverframeProvider`
+included, before it reports the error; the hook stays until the end of that
+task, so the error is still captured. The native fatal React Native raises for
+the same error (`RCTFatalException` on iOS and tvOS, `JavascriptException` on
+Android) is not reported a second time. An error in the render that first
+mounts the provider comes before this capture is installed. Errors a boundary
+catches are not reported automatically; use the callback below.
+
+### React error boundary callback
+
+An existing React class boundary can opt into handled capture. Render the
+boundary inside `EverframeProvider`:
+
+```tsx
+import * as React from 'react';
+import { EverframeProvider } from '@everframe/react-native';
+import { captureReactError } from '@everframe/react-native/integrations/react';
+
+class Boundary extends React.Component<React.PropsWithChildren, { failed: boolean }> {
+  state = { failed: false };
+  static getDerivedStateFromError() { return { failed: true }; }
+  componentDidCatch(error: unknown, info: React.ErrorInfo) {
+    captureReactError(error, info);
+  }
+  render() { return this.state.failed ? null : this.props.children; }
+}
+
+export default function App() {
+  return (
+    <EverframeProvider config={{ sdkKey: '…' }}>
+      <Boundary>
+        <RootNavigator />
+      </Boundary>
+    </EverframeProvider>
+  );
+}
+```
+
+A boundary that wraps `EverframeProvider` does not report through it: its
+fallback replaces the provider in the same commit, before `componentDidCatch`
+runs. Such a boundary reports only if its fallback renders its own
+`EverframeProvider`, which mounts before `componentDidCatch` runs. Errors that a
+boundary inside the provider catches during the provider's first commit (the
+initial render that also mounts the provider) are not captured, and they are
+not replayed. Disabled crash reporting and calls after unmount are also inert.
+In development builds, a call that finds no mounted provider logs a warning, at
+most once until a provider mounts or unmounts.
+
+The application owns fallback and recovery UI. This callback reports caught
+component errors; it does not install global renderer hooks or capture arbitrary
+async/event-handler errors. Component-stack metadata is bounded and redacted by
+the existing capture pipeline, without replacing exception frames or cause data.
+
+The original error shares accepted identity with manual and nonfatal automatic
+capture within a mount. Native refusal permits recapture; equal fingerprint keys
+can also suppress distinct objects. A later fatal escalation may report separately.
+The adapter subpath is unavailable to browser-conditioned consumers.
+
+### Local capture admission diagnostics
+
+```ts
+import { getErrorCaptureStatus } from '@everframe/react-native';
+const status = getErrorCaptureStatus();
+const { attempted, accepted, duplicateSuppressed } = status.counters.handled;
+```
+
+Snapshots are detached, contain no captured content, reset on remount, and perform
+no native query or upload. Paths are `handled` (including the boundary callback),
+`errorUtils` (including errors no boundary catches), and `rejection` (submission only). Each active attempt has one outcome:
+`accepted`, `duplicateSuppressed`, `allowanceSuppressed`, `bridgeUnavailable`,
+`nativeRefused`, `captureFailed`, `reentrantSuppressed`, `inactiveAborted`, or
+`legacyAttempted`. Counters saturate at 2,147,483,647. Existing limits are ten
+handled and ten automatic distinct keys; fatal capture bypasses them.
+
+`accepted` requires exactly true from a current native capture method. It does
+not mean upload success, server processing or outbox removal. An automatic call
+to an older native fallback is only `legacyAttempted`, regardless of its return.
+Old-binary unavailable/throwing methods are covered by unit controls, not an
+installed old-binary qualification. This snapshot excludes native queue and
+delivery observations; read those with `getReportDeliveryStatus()`. Status is
+neutral `not-mounted` without a provider, `disabled` under the crash-reporting
+veto, and `unsupported` on the browser root entry.
+
+Installed boundary qualification passes on Android API 35 arm64 emulator and
+iOS 26.5 arm64 simulator for this exact phone-host row:
+React 19.2.5, `react-native-tvos` 0.85.3-0 aliased as `react-native`, Expo
+56.0.0-preview.7, Hermes 250829098.0.10 / bytecode 98. Other RN distributions,
+versions, TV, physical devices and production endpoints are not qualified by
+this matrix. Installed checks cover four genuine boundary capture cases,
+disabled/initial zero controls, mapped causes, and byte-identical encrypted retry
+after relaunch. The application/JS builds are optimized; native SDKs are
+Debug/local. Physical-device and production-endpoint qualification remains open.
+
+### Native report delivery diagnostics
+
+`getReportDeliveryStatus()` synchronously copies cached native observations. It
+performs no file reads, uploads, drains, or hook installation. Use
+`getErrorCaptureStatus()` separately for JavaScript admission decisions.
+
+```ts
+import { getReportDeliveryStatus } from '@everframe/react-native';
+const status = getReportDeliveryStatus();
+console.log(status.status, status.queue.observation, status.queue.pendingCount);
+```
+
+The schema separates native capture acceptance, queue operations and settled
+transport attempts (`live-submit` and `outbox-drain`). `server-accepted` means an
+HTTP 2xx response; it does not establish processing, symbolication, dashboard
+visibility or queue removal. Removal has its own operation counter. Counters are
+operations, not unique reports, and saturate at 2,147,483,647.
+
+The queue is the SDK's shared report outbox, including reporter submissions and
+entries from earlier configurations. Its count is last-observed, not a fresh
+measurement or a current-project/crash-only total. Missing counts mean unknown;
+`partial` means only readable entries were counted. Android rejects new entries
+at capacity and retains terminal HTTP responses during drain. iOS can evict older
+entries and attempts removal after terminal HTTP responses. Custom standalone
+outbox/submitter instances are not automatically included.
+
+Snapshots contain only fixed codes and counters, never report content, IDs,
+URLs, credentials or exception strings. Observations are process-local and reset
+on native start/reconfiguration or kill. They are best-effort: contention and
+termination may lose observations; a busy getter reports `snapshot-busy`.
+`bridge-handled` and `bridge-automatic` cover fact entry paths shared by framework
+bridges. iOS marks `jvm-uncaught` unsupported and implies no automatic iOS native
+crash collector.
+
+Without a mounted provider the result is `not-mounted/no-mount`; the browser
+export is `unsupported/platform`. Older native SDKs without the getter return
+`unsupported/native-method-missing`. A throwing native call returns
+`unavailable/native-call-failed`, and malformed native responses return
+`unavailable/invalid-native-snapshot`. These fallbacks have an unobserved queue
+and `unknown` platform policies. This API does not provide a per-report delivery
+guarantee or trigger a retry.
+
 ## Network body capture (client veto)
 
 ```tsx
-<EverframeProvider config={{ apiKey: '…', networkBodies: { disabled: true } }}>
+<EverframeProvider config={{ sdkKey: '…', networkBodies: { disabled: true } }}>
 ```
 
 `networkBodies.disabled: true` is a **client veto** — it can only turn body
@@ -182,7 +434,7 @@ import { createNavigationContainerRef } from '@react-navigation/native';
 const navigationRef = createNavigationContainerRef();
 const txNav = reactNavigationIntegration({ navigationRef });
 
-<EverframeProvider config={{ apiKey, integrations: [consoleIntegration(), txNav] }}>
+<EverframeProvider config={{ sdkKey, integrations: [consoleIntegration(), txNav] }}>
   <NavigationContainer ref={navigationRef} onReady={txNav.onReady}>
     ...
 ```
@@ -211,7 +463,7 @@ inside a native view and never reaches JS.
 ### Config
 
 ```tsx
-<EverframeProvider config={{ apiKey, vitals: { enabled: true, sampleRate: 0.5, captureSourceQuery: false } }}>
+<EverframeProvider config={{ sdkKey, vitals: { enabled: true, sampleRate: 0.5, captureSourceQuery: false } }}>
 ```
 
 - `enabled` — absent follows the dashboard toggle; `false` opts out locally;
@@ -222,7 +474,9 @@ inside a native view and never reaches JS.
 
 **Reconfiguring.** A Provider remount with the *same* config does not restart
 the SDK: both native sides compare the incoming config against the *installed*
-one and skip the start entirely. A **changed** config does restart it — and a
+one and skip the start entirely. A **changed** config does restart it (on iOS,
+except a change confined to `releaseHealth` or the loaded bundle; see
+[Release health](#release-health)) — and a
 start supersedes the running SDK, detaching every player integration it had
 announced. **Limitation:** players tracked before that restart stay untracked
 until their screens remount; nothing re-registers them automatically. Two React
@@ -394,7 +648,7 @@ on Android), so React Native's focus engine never sees it — the native VC
 manages focus on its own UIWindow / Activity.
 
 ```tsx
-<EverframeProvider config={{ apiKey }}>
+<EverframeProvider config={{ sdkKey }}>
   <NavigationContainer>{/* focus engine root */}</NavigationContainer>
 </EverframeProvider>
 ```
@@ -520,6 +774,40 @@ recipes above.
 
 ---
 
+## Android reporter initialization
+
+The Android reporter can be opened after the host activity has resumed, including
+apps that disable AndroidX Startup. Use matching updated React Native bridge and
+`dev.everframe:reporter-ui` artifacts: the bridge supplies the current resumed
+activity, and installation and presentation run on the main thread. Repeated
+configuration with matching updated artifacts does not register another lifecycle observer. Capture configuration
+remains synchronous without waiting for reporter UI initialization.
+
+The existing `ReporterResolverInstaller.create(Context)` entry point is retained
+for compiled callers. A new bridge with an older reporter uses its legacy entry
+point when the activity-aware method is absent; that combination retains the old
+late-initialization limitation. A failure from an available method is reported,
+not retried through the legacy path. Background or unavailable activities return
+a cancelled result with reason `no_active_activity`.
+
+Legacy off-main `create(Context)` schedules installation and returns before it is
+ready; use the awaited activity-aware bridge to open immediately after configure.
+With a new bridge and an older reporter, each configure, companion start, and
+open invokes legacy installation again. This can add duplicate lifecycle
+callbacks and overwrite that older reporter's resolver and activity supplier;
+the previous bridge limited installation to once per module. Conversely, an old
+compiled bridge with the new reporter can announce companion PIN capability
+before asynchronous reporter installation finishes, temporarily advertising no
+PIN support. Use the matching updated pair for the qualified behavior.
+
+Activity destruction while a reporter is open resolves the pending call with
+`{ status: "cancelled", reason: "activity_destroyed" }`, releases that report's
+frozen replay capture, and clears presenting state so the reporter can open
+again. Backgrounding alone does not cancel the dialog. Once Send is tapped,
+submission owns the result and continues independently of activity destruction;
+its normal delivery result is preserved. Unsaved drafts are not restored after
+activity recreation.
+
 ## License
 
 MIT

package/android/build.gradle.kts

@@ -21,11 +21,10 @@
 //   spec); a host on the new architecture can flip the parent class with a
 //   1-line patch once codegen output is available in the consuming build.
 //
-// ZERO-PERMISSION:
-//   No `<uses-permission>` in AndroidManifest.xml. The bridge adds zero
-//   permissions on top of whatever `:everframe-core` declares (the core also
-//   has none — Phase 5 zero-permission AAR contract). Verified by the 06-03
-//   acceptance grep.
+// PERMISSIONS:
+//   No `<uses-permission>` in AndroidManifest.xml. The bridge adds no
+//   permissions on top of what `:everframe-core` declares (INTERNET only,
+//   merged into the host app's manifest).
 //
 // SCOPE (NOT in this build):
 //   • Namespace is `dev.everframe.rn`.
@@ -152,7 +151,9 @@ val nativeVersionOverride = (findProperty("everframeNativeVersion") as String?)
 val rnSdkPkg = groovy.json.JsonSlurper()
     .parse(file("../package.json")) as Map<*, *>
 val rnSdkVersion = rnSdkPkg["version"] as String
-val nativeMinorRange: String = nativeVersionOverride ?: "[1.0.0,1.1.0)"
+// Native 1.2.0 is the release that renamed the SDK key to `sdkKey`; the
+// bridge moves with it, ahead of package.json, which the 1.2.0 release bumps.
+val nativeMinorRange: String = nativeVersionOverride ?: "[1.2.0,1.3.0)"
 if (nativeVersionOverride != null) {
     logger.lifecycle(
         "[everframe-rn] native AAR pinned to $nativeVersionOverride via everframeNativeVersion " +

package/android/src/main/java/dev/everframe/rn/EverframeModule.kt

@@ -76,6 +76,8 @@ import dev.everframe.companion.CompanionSubmissionComposer
 import dev.everframe.companion.PreviewCapture
 import dev.everframe.companion.RelayWSClient
 import dev.everframe.companion.parseCompanionBadgePosition
+import dev.everframe.config.ReleaseHealthConfig
+import dev.everframe.config.ReleaseHealthBundleStatus
 import dev.everframe.config.CaptureConfig
 import dev.everframe.config.Environment
 import dev.everframe.config.ReportResult
@@ -105,6 +107,8 @@ class EverframeModule(
     private val reactContext: ReactApplicationContext,
 ) : NativeEverframeSpec(reactContext) {
 
+    private val reporterBridge = ReporterBridge()
+
     private val videoPrivacyAdapter = Everframe.__registerVideoPrivacyAdapter(RnVideoPrivacyAdapter)
     private val sensitiveRegistration = RnSensitiveRegistration(
         { tag -> UIManagerHelper.getUIManagerForReactTag(reactContext, tag)?.resolveView(tag) },
@@ -213,12 +217,45 @@ class EverframeModule(
     @ReactMethod(isBlockingSynchronousMethod = true)
     override fun configureSync(opts: ReadableMap): Boolean = configureInternal(opts)
 
+    private fun parseReleaseHealth(opts: ReadableMap): ReleaseHealthConfig? {
+        // Invalid bridge input revokes earlier monitoring instead of retaining an old subject.
+        // The SDK reads the app version itself; the bridge carries the loaded bundle, the user ID and
+        // whether debug builds count. Release health is on by default: a missing or null flag is on, and
+        // only an explicit false is off. It still needs a valid loaded bundle, so no id means off.
+        return runCatching {
+            if (opts.takeIfHasBoolean("releaseHealthEnabled") == false) return null
+            val loaded = opts.takeIfHasString("releaseHealthLoadedBuildId") ?: return null
+            val user = opts.takeIfHasString("releaseHealthUserId")
+            if (!validHealthText(loaded, 200) || (user != null && !validHealthText(user, 128))) return null
+            val includeDebugBuilds = opts.takeIfHasBoolean("releaseHealthIncludeDebugBuilds") ?: false
+            ReleaseHealthConfig(enabled = true, userId = user, loadedBuildId = loaded,
+                loadedBundleStatus = ReleaseHealthBundleStatus.KNOWN, includeDebugBuilds = includeDebugBuilds)
+        }.getOrNull()
+    }
+
+    private fun validHealthText(value: String, maximum: Int): Boolean {
+        // Match the wire's UTF-16 limit and ECMAScript blank definition, preserving ID bytes.
+        fun blank(c: Char) = c in '\u0009'..'\u000d' || c == ' ' || c == '\u00a0' ||
+            c == '\u1680' || c in '\u2000'..'\u200a' || c == '\u2028' || c == '\u2029' ||
+            c == '\u202f' || c == '\u205f' || c == '\u3000' || c == '\ufeff'
+        if (value.length > maximum || value.all(::blank)) return false
+        var index = 0
+        while (index < value.length) {
+            val c = value[index++]
+            if (c.code < 32 || Character.isLowSurrogate(c)) return false
+            if (Character.isHighSurrogate(c)) {
+                if (index >= value.length || !Character.isLowSurrogate(value[index++])) return false
+            }
+        }
+        return true
+    }
+
     private fun configureInternal(opts: ReadableMap): Boolean {
         var completed = false
         txGuardSurface("configure") {
-            val sdkKey = opts.takeIfHasString("apiKey")
+            val sdkKey = opts.takeIfHasString("sdkKey")
                 ?: throw JSApplicationIllegalArgumentException(
-                    "configure: required field 'apiKey' missing",
+                    "configure: required field 'sdkKey' missing",
                 )
             val sdkVersion = opts.takeIfHasString("sdkVersion") ?: Everframe.SDK_VERSION
 
@@ -231,6 +268,9 @@ class EverframeModule(
             // Polarity flips exactly once, here: JS sends the veto
             // (`installIdentifierDisabled`), native stores the permission.
             val installIdentifierDisabled = opts.takeIfHasBoolean("installIdentifierDisabled") ?: false
+            // Polarity flips exactly once, here: JS sends the veto
+            // (`crashReportingDisabled`), native stores the permission.
+            val crashReportingDisabled = opts.takeIfHasBoolean("crashReportingDisabled") ?: false
             // Attach-PIN UI mode (spec 2026-08-19) — a flat optional STRING
             // field (codegen cannot express a string-literal union), parsed
             // here and stashed for `startCompanion()` to read (the flag is a
@@ -243,12 +283,20 @@ class EverframeModule(
             val attachPinUi = parseAttachPinUi(opts.takeIfHasString("attachPinUi"))
 
             val config = EverframeConfig(
+                // The JS config carries no App ID, and the native SDK requires a
+                // non-blank one. It only keys this app's low-memory-kill issue, so
+                // the SDK key stands in, as it always has; changing it would split
+                // existing React Native low-memory issues.
                 appId = sdkKey,
                 sdkKey = sdkKey,
                 environment = Environment.production,
                 release = sdkVersion,
-                capture = CaptureConfig(networkBodies = !networkBodiesDisabled),
+                capture = CaptureConfig(networkBodies = !networkBodiesDisabled, crash = !crashReportingDisabled),
                 installIdentifierEnabled = !installIdentifierDisabled,
+                releaseHealth = parseReleaseHealth(opts),
+                // The JS facade always sends React Native's `__DEV__` (or the host's override). A missing
+                // or null key stays null so the native SDK decides for itself, as for any other caller.
+                debugBuild = opts.takeIfHasBoolean("debugBuild"),
                 // Explicit companion device-identity override (naming spec
                 // 2026-08-24) — read straight off the flat ConfigOpts field,
                 // same shape as attachPinUi above. Absent/blank falls
@@ -331,7 +379,7 @@ class EverframeModule(
                     "Everframe.rn",
                     "configure: SDK already running this exact config — skipping start()",
                 )
-                installPresenterResolverIfNeeded()
+                reporterBridge.scheduleInstall(reactContext)
                 completed = true
                 return@txGuardSurface
             }
@@ -357,10 +405,10 @@ class EverframeModule(
 
             // Wire TXReporterPresenter as the resolver for
             // Everframe.shared.report.open(). Mirrors iOS TXReporterPresenter
-            // .installResolver(). Reflective lookup keeps :sdk-react-native
-            // from a hard dependency on :everframe-reporter-ui (which the host
-            // app pulls in via its app build.gradle).
-            installPresenterResolverIfNeeded()
+            // .installResolver(). Reflection preserves compatibility with
+            // separately built reporter artifacts; the awaited open retries
+            // installation on main before selecting the resumed host.
+            reporterBridge.scheduleInstall(reactContext)
             completed = true
         }
         return completed
@@ -382,16 +430,9 @@ class EverframeModule(
             promise.reject(REJECT_CAPTURE_DISABLED, "Everframe not started (captureGate=false). Call configure() first.")
             return
         }
-        // ReporterResolverInstaller tracks the active Activity via its own
-        // ActivityRegistry — we don't pass currentActivity through. But we
-        // ensure the resolver is installed so report.open() doesn't throw.
-        installPresenterResolverIfNeeded()
-
         MainScope().launch {
             try {
-                val result: ReportResult = withContext(Dispatchers.Main) {
-                    Everframe.report.open()
-                }
+                val result: ReportResult = reporterBridge.open(reactContext)
                 val dict = Arguments.createMap().apply {
                     when (result) {
                         is ReportResult.Submitted -> {
@@ -410,7 +451,8 @@ class EverframeModule(
                 }
                 promise.resolve(dict)
             } catch (t: Throwable) {
-                promise.reject(REJECT_OPEN_REPORTER_FAILED, t.message, t)
+                promise.reject(REJECT_OPEN_REPORTER_FAILED, reporterBridge.rejectionMessage(t))
+                if (t is kotlinx.coroutines.CancellationException) throw t
             }
         }
     }
@@ -641,6 +683,10 @@ class EverframeModule(
 
     // ---------------- synchronous crash persistence ----------------
 
+    /** Copies cached native facts; never initializes storage or starts a drain. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getReportDeliveryStatusJson(): String = Everframe.getReportDeliveryStatus().toJson()
+
     /** Automatic ErrorUtils capture; true acknowledges completed sidecar storage. */
     @ReactMethod(isBlockingSynchronousMethod = true)
     override fun reportCrash(crashJson: String): Boolean = captureCrashJson(crashJson, handled = false)
@@ -670,15 +716,16 @@ class EverframeModule(
                 }
             }.getOrNull()
             val details = if (obj.has("details")) obj.get("details") else null
+            val causeChain = if (obj.has("causeChain")) obj.get("causeChain") else null
             val fatal = !handled && obj.optBoolean("fatal", false)
             val accepted = if (handled) {
-                dev.everframe.crash.CrashReporter.captureHandledFactsWithDetails(
-                    exceptionType, message, frames, occurredAt, jsBundle, details,
+                dev.everframe.crash.CrashReporter.captureHandledFactsWithCauses(
+                    exceptionType, message, frames, occurredAt, jsBundle, details, causeChain, "everframe-android",
                 )
             } else {
-                dev.everframe.crash.CrashReporter.captureFactsAcceptedWithDetails(
+                dev.everframe.crash.CrashReporter.captureFactsAcceptedWithCauses(
                     exceptionType, message, frames, obj.optString("mechanism", "errorutils"),
-                    fatal, occurredAt, jsBundle, details,
+                    fatal, occurredAt, jsBundle, details, causeChain,
                 )
             }
             // Scheduling is best-effort after acceptance; a scheduler failure
@@ -851,6 +898,10 @@ class EverframeModule(
 
     @ReactMethod
     override fun startCompanion() {
+        if (android.os.Looper.myLooper() != android.os.Looper.getMainLooper()) {
+            android.os.Handler(android.os.Looper.getMainLooper()).post { startCompanion() }
+            return
+        }
         txGuardVoid("startCompanion") {
             // Idempotent: a live client means a prior startCompanion already
             // opened the socket. Do NOT recreate it — callers must
@@ -864,13 +915,16 @@ class EverframeModule(
                 return@txGuardVoid
             }
 
+            // Await the main-thread install before the relay can announce PIN capability.
+            // configureSync itself remains non-blocking with respect to main.
+            reporterBridge.scheduleInstall(reactContext)
             installCompanionCollectorsIfNeeded()
 
             // Runtime suppression of the built-in PIN presenter (spec
             // 2026-08-19, controller ruling): a runtime flag, not an
             // install-site gate. `:everframe-reporter-ui`'s
             // `CompanionPinPresenter` is auto-installed via
-            // `ReporterResolverInstaller` (androidx.startup) regardless of
+            // `ReporterResolverInstaller` (Startup or the bridge above) regardless of
             // the configured mode, so `Everframe.__attachPinUiInstalled`
             // stays an honest capability signal — only the PRESENTING is
             // silenced, here, at the one site where the mode is already
@@ -976,6 +1030,10 @@ class EverframeModule(
 
     @ReactMethod
     override fun stopCompanion() {
+        if (android.os.Looper.myLooper() != android.os.Looper.getMainLooper()) {
+            android.os.Handler(android.os.Looper.getMainLooper()).post { stopCompanion() }
+            return
+        }
         txGuardVoid("stopCompanion") {
             // External review, finding NN1 — only ever stop/unregister OUR
             // OWN client. `companionClient` is non-null here ONLY when a
@@ -1607,34 +1665,7 @@ class EverframeModule(
 
     // ---------------- Helpers ----------------
 
-    @Volatile
-    private var resolverInstalled = false
 
-    /**
-     * Idempotently runs `ReporterResolverInstaller.create(applicationContext)`
-     * — the androidx.startup `Initializer` from :everframe-reporter-ui. Hosts
-     * using AndroidX App Startup will have this run automatically at process
-     * launch; this method covers hosts that disable App Startup (common in
-     * React Native apps) by invoking the same code path reflectively. No-op
-     * after the first successful call.
-     */
-    private fun installPresenterResolverIfNeeded() {
-        if (resolverInstalled) return
-        try {
-            val cls = Class.forName("dev.everframe.ui.ReporterResolverInstaller")
-            val ctor = cls.getDeclaredConstructor()
-            ctor.isAccessible = true
-            val instance = ctor.newInstance()
-            val create = cls.getMethod("create", android.content.Context::class.java)
-            create.invoke(instance, reactContext.applicationContext)
-            resolverInstalled = true
-        } catch (t: Throwable) {
-            android.util.Log.w(
-                "Everframe.rn",
-                "ReporterResolverInstaller not on classpath; openReporter will fail until the host app depends on :everframe-reporter-ui (${t.javaClass.simpleName}: ${t.message})",
-            )
-        }
-    }
 
     private fun ReadableMap.takeIfHasString(key: String): String? =
         if (hasKey(key) && !isNull(key)) getString(key) else null