@scalebun-release/react-native 2.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaleBun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @scalebun/react-native
+
+Production-grade React Native SDK for [ScaleBun](https://scalebun.dev) — error reporting, analytics, session replay, and in-app engagement for iOS and Android.
+
+## Installation
+
+```sh
+npm install @scalebun/react-native
+# or
+pnpm add @scalebun/react-native
+# or
+yarn add @scalebun/react-native
+```
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+Wire the AppDelegate for **OTA bundle loading** (required for OTA on iOS) and
+Direct APNs push:
+
+```sh
+npx scalebun init ios            # patch the AppDelegate (ObjC auto-patched; Swift prints steps)
+npx scalebun init ios --check    # verify hooks + OTA bundleURL exist (exit 1 if missing)
+```
+
+Like Android, iOS OTA needs the app's bundle resolution wired to the OTA slot
+(`bundleURL` → `ScaleBunOtaModule.getBundleURL()`), or updates install but never
+load. `init ios` auto-applies this to a standard ObjC AppDelegate and prints the
+exact snippet for Swift / custom `bundleURL` bodies. **Rebuild the native app
+afterwards.**
+
+### Android
+
+OTA updates need one wiring step in `MainApplication` so a downloaded bundle
+actually loads — without it an update installs, reports success, and the app
+silently keeps running the bundle baked into the APK. Run:
+
+```sh
+npx scalebun init android            # wire MainApplication for OTA bundle loading
+npx scalebun init android --check    # verify (exit 1 if missing)
+npx scalebun init android --dry-run  # preview changes without writing
+```
+
+This adds `ScaleBunOtaModule.getJSBundleFile(...)` in the form matching your
+React Native version (Kotlin is auto-patched; Java prints manual instructions).
+**Rebuild the native app afterwards** — a JS reload does not load the newly
+wired native path.
+
+For push on Android (optional): add `android/app/google-services.json`, apply
+the Google Services Gradle plugin with `@react-native-firebase/messaging`, and
+declare the `POST_NOTIFICATIONS` permission. Run `npx scalebun doctor` to see
+exactly what's missing.
+
+> Run `npx scalebun -h` to list every command — SDK setup (`doctor`, `init ios`,
+> `init android`) plus the OTA publishing commands (`login`, `ota publish`,
+> `rollout`, …).
+
+### Optional peer dependencies
+
+Some features activate only when their peer package is installed:
+
+| Feature            | Peer dependency               |
+| ------------------ | ----------------------------- |
+| Screenshot capture | `react-native-view-shot`      |
+| Push notifications | `@notifee/react-native`       |
+| Expo Router journey | `expo-router`                |
+
+## Quick start
+
+Wrap your app in the provider and pass your project credentials from the dashboard:
+
+```tsx
+import { ScaleBunProvider } from '@scalebun/react-native';
+
+export default function App() {
+  return (
+    <ScaleBunProvider
+      config={{
+        projectId: 'YOUR_PROJECT_ID',
+        publishableKey: 'YOUR_PUBLISHABLE_KEY',
+      }}
+    >
+      <RootNavigator />
+    </ScaleBunProvider>
+  );
+}
+```
+
+The default export exposes the imperative facade for use outside React (identifying users, capturing events, etc.):
+
+```ts
+import ScaleBun from '@scalebun/react-native';
+```
+
+## Business revenue telemetry
+
+Send purchases with a stable transaction ID and ISO-4217 currency. `productId`
+is the durable plan/SKU key used for grouping; `productName` is its optional
+human-readable label. Tax, fee, and discount are positive deductions from gross
+revenue, while refunds and disputes use their own transaction type.
+
+```ts
+ScaleBun.trackPurchase({
+  revenue: 29,
+  currency: 'USD',
+  transactionId: 'order_123',
+  productId: 'pro_monthly',
+  productName: 'Pro monthly',
+  quantity: 1,
+  tax: 2.1,
+  fee: 0.9,
+  discount: 0,
+});
+
+ScaleBun.trackSubscription({
+  subscriptionId: 'sub_123',
+  subscriptionEventId: 'invoice:2026-09', // optional; reuse for this same logical change
+  status: 'started',
+  plan: {
+    id: 'pro_monthly',
+    name: 'Pro monthly',
+    amount: 29,
+    currency: 'USD',
+    interval: 'month',
+  },
+});
+```
+
+Subscription lifecycle payloads use schema v2. `subscriptionId` and optional
+`subscriptionEventId` are trimmed identifiers of 1–160 characters using letters, digits, `.`, `_`,
+`:`, or `-` (the first character must be alphanumeric). Reuse `subscriptionEventId` only for the
+same logical lifecycle change. The backend scopes it to the app and environment and keeps the first
+accepted payload. Without it, the SDK-generated envelope ID still makes transport and offline
+retries idempotent, but a repeated host call is a new event.
+
+The SDK, not custom properties, stamps the schema and ledger identity. SDK/server provenance is
+derived from the authenticated ingestion route and cannot be claimed by the app. React Native does
+not invent a Web replay coordinate for subscription events. Invalid/bounded events are dropped;
+`ScaleBun.events.stats()` exposes `{ pending, dropped }` for integration diagnostics.
+
+Recognised revenue, collected cash, currency conversion, and billing-source
+provenance are server-side measurements; the SDK does not infer them.
+
+## Requirements
+
+- React Native `>= 0.74`
+- React `>= 18`
+
+## License
+
+MIT © ScaleBun

package/android/build.gradle

@@ -0,0 +1,94 @@
+plugins {
+    id 'com.android.library'
+    id 'org.jetbrains.kotlin.android'
+}
+
+/**
+ * Backward-compatible build for both React Native architectures.
+ *
+ * New Architecture: applies the React Native Gradle plugin (runs TurboModule
+ * codegen from `codegenConfig` in package.json) and compiles the `src/newarch`
+ * bridge wrappers, which implement the generated `Native*Spec` base classes.
+ *
+ * Old Architecture: compiles the `src/oldarch` wrappers (classic NativeModule).
+ *
+ * Either way the actual capture logic lives in `com.scalebun.core` (shared,
+ * architecture-agnostic) — the wrappers are thin glue only.
+ */
+def isNewArchitectureEnabled() {
+    return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
+}
+
+if (isNewArchitectureEnabled()) {
+    apply plugin: 'com.facebook.react'
+}
+
+android {
+    namespace 'com.scalebun.sdk'
+    compileSdk 34
+
+    buildFeatures {
+        // Exposes BuildConfig.IS_NEW_ARCHITECTURE_ENABLED so the (shared, main
+        // source set) package can flag the Crash module as a TurboModule only
+        // on New Arch, while staying a legacy module on Old Arch.
+        buildConfig true
+    }
+
+    defaultConfig {
+        minSdk 24
+        targetSdk 34
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+        // Ship R8 keep-rules to consumer apps so release minification doesn't
+        // strip the native modules / codegen TurboModule specs.
+        consumerProguardFiles "consumer-rules.pro"
+        // Runs the OTA RSA verifier instrumentation test on-device
+        // (src/androidTest) — proves SHA256withRSA on the device provider across
+        // API levels. Affects only this library's connectedAndroidTest task.
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    sourceSets {
+        main {
+            java.srcDirs = ['src/main/java']
+            manifest.srcFile 'src/main/AndroidManifest.xml'
+
+            // Architecture-specific bridge wrappers (populated in Phase 2).
+            // Pointing at a not-yet-created dir is a harmless no-op until then.
+            if (isNewArchitectureEnabled()) {
+                java.srcDirs += ['src/newarch/java']
+            } else {
+                java.srcDirs += ['src/oldarch/java']
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-android'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
+
+    // Google Play Install Referrer — reads the install-time referrer string for
+    // deterministic Android attribution (ScaleBunInstallReferrerModule). Small,
+    // Play-only lib; degrades gracefully (the module rejects) where Play is absent.
+    implementation 'com.android.installreferrer:installreferrer:2.2'
+
+    // Engage push-token acquisition (FCM). Declared compileOnly so the SDK does
+    // NOT force Firebase onto host apps that don't use push: ScaleBunEngageModule reaches
+    // FirebaseMessaging purely via reflection and fails soft (logged skip) when the
+    // class is absent at runtime. Host apps that want push add the real
+    // firebase-messaging dependency in their own app module — additive, no break.
+    compileOnly 'com.google.firebase:firebase-messaging:23.4.1'
+
+    // On-device OTA verifier test only (src/androidTest) — not shipped to consumers.
+    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
+    androidTestImplementation 'androidx.test:runner:1.5.2'
+}

package/android/consumer-rules.pro

@@ -0,0 +1,28 @@
+# ScaleBun React Native SDK — R8/ProGuard consumer rules.
+#
+# Applied automatically to consumer apps (via `consumerProguardFiles` in
+# build.gradle). Without these, release builds with minification can strip the
+# native modules and the codegen TurboModule specs, causing "module not found"
+# at runtime on the New Architecture.
+
+# Keep all ScaleBun native classes. The SDK's native code is reflection- and
+# JNI-accessed (RN resolves modules by getName()/@ReactMethod; codegen specs are
+# referenced from generated C++/JNI), so it must not be renamed or removed.
+-keep class com.scalebun.** { *; }
+
+# Codegen-generated TurboModule specs (com.scalebun.spec.NativeScaleBun*Spec / NativeReplaySdkSpec).
+-keep class com.scalebun.spec.** { *; }
+
+# Google Play Install Referrer client — used by ScaleBunInstallReferrerModule for
+# deterministic Android acquisition attribution. Kept so release minification
+# doesn't strip the referrer client.
+-keep class com.android.installreferrer.** { *; }
+
+# Defensive React Native bridge reflection (RN ships equivalents, kept here so the
+# SDK is self-contained even if app rules differ).
+-keepclassmembers class * extends com.facebook.react.bridge.ReactContextBaseJavaModule {
+    @com.facebook.react.bridge.ReactMethod <methods>;
+}
+-keep class * extends com.facebook.react.bridge.NativeModule { *; }
+-keep class * extends com.facebook.react.BaseReactPackage { *; }
+-keep class * extends com.facebook.react.turbomodule.core.interfaces.TurboModule { *; }

package/android/src/androidTest/java/com/scalebun/rn/ota/ScaleBunOtaVerifierInstrumentedTest.kt

@@ -0,0 +1,112 @@
+package com.scalebun.rn.ota
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * On-device verification for SB-OTA-RSA-SHA256-V1 (PROMPT §22).
+ *
+ * Proves that the shared committed vector (packages/ota-protocol/fixtures — the
+ * SAME bytes the Node codec, backend, and JVM parity harness use) verifies with
+ * the DEVICE's `SHA256withRSA` provider and parses with the on-device codec, and
+ * that tampering / unknown keys are rejected. RSA verification + RSA KeyFactory
+ * ship on every supported Android API level, so this must pass on the repo's
+ * minSdk (24), on an API below 33, and on API 33+ — run it on each:
+ *
+ *   ./gradlew :scalebun_react-native:connectedAndroidTest   # per running emulator/AVD
+ *
+ * The constants below are copied verbatim from fixtures/vectors/full.json; the
+ * cross-repo parity harness keeps the codec byte-identical, so a drift here shows
+ * up as a verification failure.
+ */
+@RunWith(AndroidJUnit4::class)
+class ScaleBunOtaVerifierInstrumentedTest {
+
+    private val signedPayloadB64 =
+        "U0JPVEEwMDEAAQAAABRTQi1PVEEtUlNBLVNIQTI1Ni1WMQAAAAdTSEEtMjU2AAAAFXRlc3QtcnNhLTMwNzItMjAyNi0wMQAAAA5wcm9qX3Rlc3RfMDAwMQAAABVvcmcuc2NhbGVidW4ubGVnYXJhZ2UAAAANcmVsX2Z1bGxfMDAwMQAAAA5ibmRsX2Z1bGxfMDAwMQAAAAdhbmRyb2lkAAAABGZ1bGwAAAAFNC41LjkAAAAGMC43NC4xAAAAAjI0AAAAAAAAACoAAAAAaVW5AAAAAAAAAAAAAAAAAAAAAWD6bpV7WCc0zBI9NJ6rivyixtOu66jZ7EYSJniR99yQMwAAAAAAAAAA+m6Ve1gnNMwSPTSeq4r8osbTruuo2exGEiZ4kffckDM="
+    private val signatureB64 =
+        "jlC7GRLWKXku3cbqtODlFt+qn2CEmS3oHOr9QTopCCzEovUF5a2GRT0PQ5k2C5EX7UGGO0Sv6/WhkznKR9NVEZl6ed0KARHAY8zfwTjin3czx9jpwV9bfsLlxEoKNo9bPfIs3mc0VoHCWOp95hQAotG+GqEwYsXqPruZ43U87qWT0t9/a3QboX+07hPO5vI4fDZQuPeo3W1HmXPKbOB7QGSijtKgKwQNuJHz+etsVsQelDsDofRSpYV92XCheUWWHP7kZKFOCcYUXnVwJcdU0Jhej+22vAESRK2G0CXP3orXE4pASaA3y4wkBQgJAJkcTN/ic1/Wm5BLo7KH+ypK1eo0hnrrLNSh6E+St5NvxlTM3bmxwnwHkPMYVBuOT0fUJy+gbD1/1CPvKakL12vizKwWDYuhfcIGkQUTvP2zCxcqWLfmZ7ZGo6n6WXMX63Vz+IQG0tnx1cp6YqJVIgxqjskQ47sacsfS9QeV5LyJhvBQrDSbpqujo9la8dDzZfDN"
+    private val keyId = "test-rsa-3072-2026-01"
+    private val projectId = "proj_test_0001"
+    private val applicationId = "org.scalebun.legarage"
+
+    private val spkiPem =
+        "-----BEGIN PUBLIC KEY-----\n" +
+        "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAt3tfFTPE+lkEbFeYi6zE\n" +
+        "+uI+3oJl0HfKtGTh7sr7pSh/uPJq2giF0Uc09ux3Z0i4NlqpOyLmiIrVOgYcWcN+\n" +
+        "/pCl1mh6VmT7nYO3sEhL+HyaIaclCGxvHCJSsaVHH8qQyiCVUypWWKN0L38U4isN\n" +
+        "dJ2x+Wv7iLSZu3oM+ZDyGWCjRLE49jKNl0tfaQX6G1YoyBi1aEu5sWIQ6LjGE4IX\n" +
+        "1AJtOiNoaO9orjVgphA5FDKFFqguhEJrHoSXt3awHaeCYFm/mt+NI6k4sRf59UNx\n" +
+        "hdGh0kVL/6jZncclxueFafOOdfPf+jF3ylTczQhnID7Mg1PdmjXR7cfq7jDdjzfW\n" +
+        "VICJqGt+EhUd92pWrMTa5k3SDin3EetYGJsN7iKLbAl0D6Uy8RfE2mdsF2K6D3EP\n" +
+        "9waHN7vLURCF//TGy84FxPy7vbFgLO4oT07lxaopuGX7vOdONI8qLcFhEAJ9fRVN\n" +
+        "lqPWQGib0iAKE+gLl4CWZen674QZF39fGnOBEz7JsmDfAgMBAAE=\n" +
+        "-----END PUBLIC KEY-----\n"
+
+    private fun registry() = ScaleBunOtaKeyRegistry.fromJson(
+        JSONObject()
+            .put("projectId", projectId)
+            .put("keys", org.json.JSONArray().put(JSONObject().put("keyId", keyId).put("publicKey", spkiPem)))
+            .toString(),
+    )
+
+    private fun context(currentSequence: Long = 0L) = ExpectedContext(
+        projectId = projectId,
+        applicationId = applicationId,
+        currentSequence = currentSequence,
+        nowEpochSeconds = 1_767_225_600L + 60, // just after the vector's issuedAt
+    )
+
+    private fun envelope(payload: String = signedPayloadB64, sig: String = signatureB64) = JSONObject()
+        .put("protocol", OtaProtocol.SIGNATURE_ALGORITHM)
+        .put("keyId", keyId)
+        .put("signedPayload", payload)
+        .put("signature", sig)
+        .toString()
+
+    @Test
+    fun genuineReleaseVerifiesOnDevice() {
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(), context(), registry())
+        assertTrue("expected ok, got ${v.code}", v.ok)
+        assertEquals("bndl_full_0001", v.payload?.bundleId)
+        assertEquals(42L, v.payload?.releaseSequence)
+        assertEquals("android", v.payload?.platform)
+        // result == artifact hash for a full release
+        assertEquals(v.payload?.artifactSha256, v.payload?.resultArtifactSha256)
+    }
+
+    @Test
+    fun oneBytePayloadMutationRejected() {
+        val bad = signedPayloadB64.dropLast(2) + if (signedPayloadB64.endsWith("M=")) "N=" else "M="
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(payload = bad), context(), registry())
+        assertTrue(!v.ok)
+        // Either the flipped base64 fails to decode canonically or the signature fails.
+        assertTrue(v.code == OtaFailureCode.INVALID_SIGNATURE || v.code == OtaFailureCode.INVALID_BASE64)
+    }
+
+    @Test
+    fun unknownKeyRejected() {
+        val emptyReg = ScaleBunOtaKeyRegistry.fromJson(
+            JSONObject().put("projectId", projectId).put("keys", org.json.JSONArray()).toString(),
+        )
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(), context(), emptyReg)
+        assertEquals(OtaFailureCode.UNKNOWN_KEY_ID, v.code)
+    }
+
+    @Test
+    fun downgradeRejected() {
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(), context(currentSequence = 100L), registry())
+        assertEquals(OtaFailureCode.RELEASE_DOWNGRADE_REJECTED, v.code)
+    }
+
+    @Test
+    fun sha256WithRsaAvailableOnThisApiLevel() {
+        // The whole point of RSA over ed25519: this must not throw on any API level.
+        java.security.Signature.getInstance("SHA256withRSA")
+        java.security.KeyFactory.getInstance("RSA")
+    }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,14 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.scalebun.sdk">
+
+    <!-- The SDK uploads telemetry (crashes, replay frames, performance) over the
+         network. Host RN/Expo apps normally declare INTERNET already; declaring it
+         here ensures it is present via manifest merging. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <!-- [Slice D] Engage feedback voice notes (opt-in; requested at runtime before record). -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+
+    <!-- Screen capture for session replay uses PixelCopy against the Activity
+         window — no special permission required. -->
+</manifest>

package/android/src/main/java/com/scalebun/core/crash/CrashStorage.kt

@@ -0,0 +1,155 @@
+package com.scalebun.core.crash
+
+import android.content.Context
+import org.json.JSONObject
+import java.io.File
+
+/**
+ * Persists a single crash record to internal storage.
+ * Written synchronously in the UncaughtExceptionHandler before the process dies.
+ * Read and cleared on next launch via ScaleBunCrashModule.drainPendingCrash().
+ */
+internal object CrashStorage {
+
+    private const val FILE_NAME = "scalebun_native_crash.json"
+
+    /**
+     * The session that is live RIGHT NOW, written once per session and read by the crash handler.
+     *
+     * WHY A SEPARATE FILE, AND WHY WRITTEN AHEAD OF TIME.
+     *
+     * A crash record survives the process; the JS session id did not, because it only ever existed
+     * in JS memory. So on the next launch there was nothing to attribute the crash to except
+     * whichever session had just been created — the crash from session A landed on session B.
+     *
+     * The fix is not to hand the id to the crash handler (a fatal handler cannot call into JS, and
+     * must not allocate or block), but to make sure it is ALREADY ON DISK before any crash can
+     * happen. This file is that guarantee: written once when a session starts, read synchronously
+     * inside `uncaughtException`.
+     *
+     * Kept separate from the crash record so a stale id can never resurrect a cleared crash, and so
+     * clearing a drained crash does not disturb the live session's identity.
+     */
+    private const val SESSION_FILE_NAME = "scalebun_active_session.txt"
+
+    /**
+     * Record the session that is now live. Called once per session from JS, never per event.
+     *
+     * Synchronous by design: it must be durable before the next line of app code runs, because the
+     * next line of app code is exactly what might crash. One small write per session is affordable;
+     * the same write per event would not be.
+     */
+    fun setActiveSessionId(context: Context, sessionId: String?) {
+        try {
+            val file = File(context.filesDir, SESSION_FILE_NAME)
+            if (sessionId.isNullOrEmpty()) file.delete() else file.writeText(sessionId)
+        } catch (_: Exception) {
+            // A missing session id degrades attribution; it must never break the app.
+        }
+    }
+
+    /**
+     * The live session id, or null.
+     *
+     * Called from the uncaught-exception handler, so it does exactly one thing: read a small file.
+     * No allocation beyond the string, no locks, no JS, no network.
+     */
+    fun activeSessionId(context: Context): String? {
+        return try {
+            val file = File(context.filesDir, SESSION_FILE_NAME)
+            if (!file.exists()) null else file.readText().trim().ifEmpty { null }
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    /**
+     * How many undelivered crashes we keep.
+     *
+     * One process produces one fatal crash, so this is not about a burst — it is about a device
+     * that crashes, restarts offline, and crashes again before the first crash could be uploaded.
+     * With a single fixed filename the second crash silently overwrote the first.
+     *
+     * Three is deliberately small: crashes are only pending while delivery is failing, and an
+     * unbounded spool on a device that crashes in a loop is its own bug. When full, the OLDEST is
+     * dropped — a fresh crash is better evidence than a stale one, and the alternative (dropping the
+     * new one) would hide an ongoing crash loop behind the first crash of the day.
+     */
+    private const val MAX_PENDING = 3
+    private const val PREFIX = "scalebun_native_crash"
+
+    /** Every pending crash file, oldest first. */
+    private fun pendingFiles(context: Context): List<File> =
+        (context.filesDir.listFiles { f -> f.name.startsWith(PREFIX) && f.name.endsWith(".json") }
+            ?: emptyArray())
+            .sortedBy { it.lastModified() }
+
+    /**
+     * Persist a crash. Each gets its own file and its own STABLE id.
+     *
+     * The id is generated HERE, once, when the crash is first written — never at upload time. It is
+     * what makes retry safe: the backend dedupes on it, so the same crash delivered any number of
+     * times produces one record. An id minted per attempt would defeat that completely.
+     */
+    fun write(context: Context, crashData: JSONObject) {
+        try {
+            val crashId = crashData.optString("crashId", "").ifEmpty {
+                // Time + identity hash: unique in practice, and derivable without allocation-heavy
+                // APIs so the same scheme can be mirrored on the signal path.
+                "crash-${System.currentTimeMillis()}-${android.os.Process.myPid()}"
+            }
+            crashData.put("crashId", crashId)
+
+            val existing = pendingFiles(context)
+            if (existing.size >= MAX_PENDING) {
+                existing.take(existing.size - MAX_PENDING + 1).forEach { runCatching { it.delete() } }
+            }
+            File(context.filesDir, "$PREFIX-$crashId.json").writeText(crashData.toString())
+        } catch (_: Exception) {
+            // Must not throw — called from uncaught exception handler
+        }
+    }
+
+    /**
+     * Every pending crash, WITHOUT deleting anything.
+     *
+     * Read used to clear as a side effect, so a failed upload lost the crash permanently: the only
+     * durable copy was destroyed before anyone knew the network had worked. Deletion is now a
+     * separate, explicit act performed after the backend accepts — see [clearCrash].
+     */
+    fun readAll(context: Context): List<JSONObject> =
+        pendingFiles(context).mapNotNull { f ->
+            runCatching { JSONObject(f.readText()) }.getOrNull()
+        }
+
+    /** Drop one delivered crash by its stable id. Safe to call for an id that is already gone. */
+    fun clearCrash(context: Context, crashId: String) {
+        try {
+            File(context.filesDir, "$PREFIX-$crashId.json").delete()
+            // Legacy single-file record predating per-crash ids.
+            if (crashId.isEmpty()) File(context.filesDir, FILE_NAME).delete()
+        } catch (_: Exception) {}
+    }
+
+    /**
+     * The LEGACY single-file record, kept only so a crash written by a previous SDK version is not
+     * stranded on disk after an app update. Read non-destructively like everything else now.
+     */
+    fun read(context: Context): JSONObject? {
+        return try {
+            val file = File(context.filesDir, FILE_NAME)
+            if (!file.exists()) null else JSONObject(file.readText())
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    fun clear(context: Context) {
+        try {
+            File(context.filesDir, FILE_NAME).delete()
+        } catch (_: Exception) {}
+    }
+
+    fun hasPending(context: Context): Boolean =
+        File(context.filesDir, FILE_NAME).exists()
+}

package/android/src/main/java/com/scalebun/core/crash/NativeCrashHandler.kt

@@ -0,0 +1,93 @@
+package com.scalebun.core.crash
+
+import android.content.Context
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Installs a Thread.UncaughtExceptionHandler that persists crash data before
+ * delegating to the original handler.
+ *
+ * The existing default handler (Android's CrashHandler / RN's DevSupportManager)
+ * is preserved and called after the crash is written — app behavior is unchanged.
+ *
+ * Crash data is stored to a file by CrashStorage and drained on next launch
+ * via ScaleBunCrashModule.drainPendingCrash().
+ */
+class NativeCrashHandler private constructor(
+    private val context: Context,
+    private val originalHandler: Thread.UncaughtExceptionHandler?,
+) : Thread.UncaughtExceptionHandler {
+
+    override fun uncaughtException(thread: Thread, throwable: Throwable) {
+        try {
+            val stackArray = JSONArray()
+            for (frame in throwable.stackTrace) {
+                stackArray.put("${frame.className}.${frame.methodName}(${frame.fileName}:${frame.lineNumber})")
+            }
+
+            // Include root cause if chained
+            val cause = throwable.cause
+            val causeInfo: JSONObject? = if (cause != null) {
+                val causeStack = JSONArray()
+                for (frame in cause.stackTrace) {
+                    causeStack.put("${frame.className}.${frame.methodName}(${frame.fileName}:${frame.lineNumber})")
+                }
+                JSONObject().apply {
+                    put("exceptionType", cause.javaClass.name)
+                    put("message", cause.message ?: "")
+                    put("stackTrace", causeStack)
+                }
+            } else null
+
+            val data = JSONObject().apply {
+                put("name", "crash.native")
+                put("exceptionType", throwable.javaClass.name)
+                put("message", throwable.message ?: "")
+                put("stackTrace", stackArray)
+                put("threadName", thread.name)
+                put("timestamp", System.currentTimeMillis().toDouble())
+                put("platform", "android")
+                if (causeInfo != null) put("cause", causeInfo)
+
+                /**
+                 * The session this crash actually belongs to.
+                 *
+                 * Read from disk, where it was written when the session started — NOT asked for
+                 * now. A fatal handler cannot call into JS, and the JS thread may already be gone.
+                 * Without this the crash arrives on the next launch with no identity, and gets
+                 * attributed to whichever session exists by then: the crash from session A lands
+                 * on session B, marking a healthy session crashed and a crashed one clean.
+                 *
+                 * Omitted rather than written empty when unknown (a crash before any session
+                 * started), so the reader can tell "no session" from "session ''".
+                 */
+                CrashStorage.activeSessionId(context)?.let { put("sessionId", it) }
+            }
+
+            CrashStorage.write(context, data)
+        } catch (_: Exception) {
+            // Must not throw — we are already in the crash path
+        }
+
+        originalHandler?.uncaughtException(thread, throwable)
+    }
+
+    companion object {
+        @Volatile private var installed = false
+
+        fun install(context: Context) {
+            if (installed) return
+            val originalHandler = Thread.getDefaultUncaughtExceptionHandler()
+            Thread.setDefaultUncaughtExceptionHandler(
+                NativeCrashHandler(context.applicationContext, originalHandler)
+            )
+            installed = true
+        }
+
+        /** For testing — resets installation flag. Do not call in production. */
+        internal fun resetForTest() {
+            installed = false
+        }
+    }
+}