clintplay-react-native 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# clintplay-react-native
+
+Session capture SDK for React Native / Expo apps — companion to [`clintplay-sdk`](../sdk) (web). Captures lifecycle, screen dimensions, navigation, JS errors, network requests (Fetch & XHR/Axios), console output, touches (screen-relative & target-relative), and native visual wireframe replay on iOS and Android.
+
+> **Status:** `0.1.0` — Production-ready JS runtime and Native TurboModule. Supports native view hierarchy traversal on iOS (`ios/ClintplayRN.mm`) and Android (`android/.../ClintplayRNModule.kt`), visual wireframe session replay, network interception for `fetch` and `XMLHttpRequest`/Axios, automatic navigation tracking, and intelligent auto-masking for sensitive fields.
+
+## Install
+
+```bash
+pnpm add clintplay-react-native
+# or
+npm install clintplay-react-native
+```
+
+Peer deps: `react >=18`, `react-native >=0.74`. Optional peer: `@react-native-async-storage/async-storage` (enables the offline retry queue when present). Tested against Expo SDK 54 / RN 0.81 with New Architecture enabled.
+
+In your `app.json`, register the config plugin:
+
+```json
+{
+  "expo": {
+    "plugins": ["clintplay-react-native"]
+  }
+}
+```
+
+## Quick start
+
+```tsx
+// app/_layout.tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  Clintplay,
+  ClintplayCaptureProvider,
+  ClintplayNavigationTracker,
+} from 'clintplay-react-native';
+
+Clintplay.init({
+  apiUrl: process.env.EXPO_PUBLIC_CLINTPLAY_URL!,
+  apiKey: process.env.EXPO_PUBLIC_CLINTPLAY_KEY,
+  asyncStorage: AsyncStorage,        // enables offline retry queue
+  captureWireframe: true,            // native visual replay snapshots
+  wireframeIntervalMs: 1000,         // snapshot interval (default: 1000ms)
+  captureNetwork: true,              // fetch + XMLHttpRequest/axios (on by default)
+  captureConsole: false,             // opt-in console.warn/error
+  captureConsoleLog: false,          // opt-in console.log (requires captureConsole: true)
+  // sampleRate: 1.0,
+  // debug: false,
+});
+
+export default function RootLayout() {
+  return (
+    <ClintplayCaptureProvider>
+      <ClintplayNavigationTracker />
+      <YourApp />
+    </ClintplayCaptureProvider>
+  );
+}
+```
+
+`init()` is a no-op when `apiUrl` is empty, so it is safe to call unconditionally in all environments.
+
+## API Reference
+
+| Call | What it does |
+| --- | --- |
+| `Clintplay.init(config)` | Boot the SDK once at app start. Idempotent. |
+| `Clintplay.identify(userId, traits?)` | Tag the current session with a user id and optional metadata. Pass `null` on logout. |
+| `Clintplay.trackScreen(path, from?)` | Emit a screen navigation event manually. (Alternatively, use `<ClintplayNavigationTracker />` or `useClintplayNavigationTracking()`). |
+| `Clintplay.reportError(err)` | Manually surface a caught error. Uncaught errors are captured automatically via `ErrorUtils.setGlobalHandler`. |
+| `Clintplay.flush()` | Force-flush the event buffer (e.g. on backgrounding). |
+| `Clintplay.stop()` | Tear down listeners, interceptors, and timers. |
+| `Clintplay.current()` | Inspect the current session ID and user ID (for breadcrumbs or support tickets). |
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiUrl` | `string` | *(required)* | Backend ingestion URL. If omitted or empty, `init()` safely no-ops. |
+| `apiKey` | `string` | `undefined` | Optional Bearer auth token for ingestion batches. |
+| `enabled` | `boolean` | `true` | Master killswitch. Set to `false` to disable all telemetry. |
+| `sampleRate` | `number` | `1.0` | Probabilistic sampling rate between `0.0` and `1.0`. |
+| `captureWireframe` | `boolean` | `false` | Enable native view-hierarchy visual wireframe capture for session replay. |
+| `wireframeIntervalMs` | `number` | `1000` | Wireframe snapshot interval in milliseconds. |
+| `captureNetwork` | `boolean` | `true` | Intercept `globalThis.fetch` and `XMLHttpRequest` (including Axios) requests. |
+| `captureConsole` | `boolean` | `false` | Intercept `console.warn` and `console.error` logs. |
+| `captureConsoleLog` | `boolean` | `false` | Intercept `console.log` logs when `captureConsole: true`. |
+| `sanitizeUrl` | `(url: string) => string` | `stripQuery` | Custom URL sanitizer function for network requests. Default strips query strings. |
+| `excludeEventTypes` | `EventType[]` | `[]` | Explicitly drop specific event types (`'wireframe'`, `'network'`, `'touch'`, `'log'`, etc.). |
+| `flushIntervalMs` | `number` | `5000` | Periodic buffer flush interval. |
+| `flushSize` | `number` | `50` | Buffer size threshold triggering an immediate flush. |
+| `maxBufferSize` | `number` | `1000` | Ring buffer capacity before oldest events are dropped. |
+| `asyncStorage` | `AsyncStorageLike` | `undefined` | Storage adapter (e.g., `@react-native-async-storage/async-storage`) for offline queue persistence. |
+| `debug` | `boolean` | `false` | Enable verbose diagnostic logging prefixed with `[clintplay-rn]`. |
+
+## Capture Sources
+
+| Event Type | Source | Default | Details |
+| --- | --- | --- | --- |
+| `meta` | SDK Bootstrap & Session Rotation | **On** | Session ID, SDK version, device platform, OS version. |
+| `screen` | `Dimensions` listener | **On** | Screen width, height, scale factor, and orientation (`portrait`/`landscape`). |
+| `lifecycle` | `AppState` listener | **On** | Application state transitions (`active`, `background`, `inactive`). |
+| `error` | `ErrorUtils.setGlobalHandler` | **On** | Uncaught exceptions with message, stack trace, and fatal flag. Non-interfering with Sentry. |
+| `network` | `fetch` & `XMLHttpRequest` / Axios | **On** | HTTP method, URL (sanitized), status code, duration, and errors. Protected against double-counting. |
+| `navigation` | Navigation Trackers & `trackScreen` | **On (Tracker)** | Screen path changes (`to`, `from`). Automatic via `<ClintplayNavigationTracker />` or React Navigation listener. |
+| `touch` | `<ClintplayCaptureProvider>` | **Provider** | Tap / touch gestures with both screen-relative coordinates (`screenX`, `screenY`) and target-relative coordinates (`x`, `y`). |
+| `wireframe` | Native TurboModule | **Opt-in** | Visual UI hierarchy snapshots (view rects, styles, text, masking) across iOS and Android. |
+| `log` | Console Interceptor | **Opt-in** | Console output (`warn`, `error`, and optional `log`). |
+| `identify` | `Clintplay.identify()` | **Manual** | Associating sessions with authenticated users and custom traits. |
+
+## Navigation Tracking
+
+### Expo Router
+
+Add `<ClintplayNavigationTracker />` at the root inside your layout:
+
+```tsx
+// app/_layout.tsx
+import { ClintplayCaptureProvider, ClintplayNavigationTracker } from 'clintplay-react-native';
+
+export default function RootLayout() {
+  return (
+    <ClintplayCaptureProvider>
+      <ClintplayNavigationTracker />
+      <Slot />
+    </ClintplayCaptureProvider>
+  );
+}
+```
+
+The tracker uses `useSegments()` / `usePathname()` when running under Expo Router to emit navigation events automatically on route changes.
+
+### React Navigation
+
+Use `createClintplayNavigationStateListener` on your `NavigationContainer`:
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { createClintplayNavigationStateListener } from 'clintplay-react-native';
+
+const onStateChange = createClintplayNavigationStateListener();
+
+export default function App() {
+  return (
+    <NavigationContainer onStateChange={onStateChange}>
+      <RootStackNavigator />
+    </NavigationContainer>
+  );
+}
+```
+
+Or use the hook directly:
+
+```tsx
+import { useClintplayNavigationTracking } from 'clintplay-react-native';
+
+function MyNavigationComponent() {
+  useClintplayNavigationTracking({
+    onNavigate: (to, from) => {
+      // custom handling if needed, Clintplay.trackScreen is called by default
+    },
+  });
+  return <NavigationStack />;
+}
+```
+
+## Coordinate Tracking (`screenX`, `screenY`)
+
+`<ClintplayCaptureProvider>` listens to bubble-phase touch responder events without intercepting touches from downstream buttons or lists.
+
+Each touch event captures:
+- `screenX`, `screenY`: Screen-relative coordinates (derived from `nativeEvent.pageX` / `nativeEvent.pageY`). These are ideal for session replay cursor rendering and heatmaps.
+- `x`, `y`: Target-relative coordinates (derived from `nativeEvent.locationX` / `nativeEvent.locationY`).
+
+## Privacy, Masking & Redaction
+
+### Automatic Masking Heuristics
+
+When `captureWireframe: true` is enabled, the native traversal engines on iOS and Android automatically redact sensitive views before building the wireframe payload:
+- **iOS**: Views with `isSecureTextEntry == YES` on `UITextField`, or `textContentType` matching `password`, `newPassword`, `creditCardNumber`, or `oneTimeCode`.
+- **Android**: `EditText` views with `inputType` matching password variations (`TYPE_TEXT_VARIATION_PASSWORD`, `TYPE_TEXT_VARIATION_WEB_PASSWORD`, `TYPE_NUMBER_VARIATION_PASSWORD`, etc.) or when using `PasswordTransformationMethod`.
+
+### Explicit Masking Components
+
+To redact custom subtrees or images, use the built-in masking components:
+
+```tsx
+import {
+  ClintplayMaskView,
+  ClintplayMaskTextInput,
+  ClintplayMaskImage,
+} from 'clintplay-react-native';
+
+// Redact an entire component subtree
+<ClintplayMaskView>
+  <Text>Sensitive account balance: $1,000,000</Text>
+</ClintplayMaskView>
+
+// Drop-in masked input & image replacements
+<ClintplayMaskTextInput value={ssn} onChangeText={setSsn} />
+<ClintplayMaskImage source={{ uri: photoUrl }} style={styles.photo} />
+```
+
+Under the hood, these components set `nativeID="clintplay-mask"`, instructing the native TurboModule to redact their geometry and contents.
+
+## Offline Retry Queue
+
+Provide an `AsyncStorage` instance in `Clintplay.init({ asyncStorage })`. When the device loses network connectivity, failed batches are persisted to disk and automatically drained upon reconnection or next application boot. The queue features an LRU eviction policy with a 5 MiB storage cap.
+
+## Known Limitations & Sentry Integration
+
+- **Console & Error Interception Order**: If using Sentry or other APM tools alongside `clintplay-react-native`, initialize `Clintplay.init()` after Sentry. Both SDKs maintain chain-safe handlers, but initialization order ensures all breadcrumbs and crash reports route cleanly.
+- **Native View Hierarchy Testing**: Visual wireframe capture requires running on a real device or simulator with the TurboModule linked. When running in web environments or bare Node unit test runners, wireframe capture gracefully falls back to empty node sets.
+
+## Scripts
+
+```bash
+pnpm test       # vitest run
+pnpm typecheck  # tsc --noEmit
+pnpm build      # tsup → dist/{cjs,esm,dts}
+```
+

package/android/build.gradle

@@ -0,0 +1,50 @@
+buildscript {
+  // Match the consumer app's Kotlin version so we don't drag in a
+  // conflicting toolchain. Most modern Expo SDK 54 / RN 0.81 apps
+  // ship Kotlin 1.9.x.
+  ext.kotlin_version = rootProject.ext.kotlin_version ?: '1.9.24'
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.6.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+def getExtOrDefault(name, defaultValue) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : defaultValue
+}
+
+android {
+  namespace 'digital.clint.clintplay'
+  compileSdk getExtOrDefault('compileSdkVersion', 34)
+
+  defaultConfig {
+    minSdk getExtOrDefault('minSdkVersion', 24)
+    targetSdk getExtOrDefault('targetSdkVersion', 34)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = '17'
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation 'com.facebook.react:react-android'
+}

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/java/digital/clint/clintplay/ClintplayRNModule.kt

@@ -0,0 +1,362 @@
+package digital.clint.clintplay
+
+import android.app.Activity
+import android.content.Context
+import android.graphics.drawable.ColorDrawable
+import android.graphics.drawable.Drawable
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.text.InputType
+import android.text.method.PasswordTransformationMethod
+import android.view.View
+import android.view.ViewGroup
+import android.view.WindowManager
+import android.widget.EditText
+import android.widget.TextView
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.turbomodule.core.interfaces.TurboModule
+import org.json.JSONArray
+import org.json.JSONObject
+import java.lang.reflect.Method
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+import java.util.concurrent.atomic.AtomicReference
+import kotlin.math.round
+
+// Android side of the Clintplay TurboModule.
+//
+// Walks the Android View hierarchy from the active Activity's decorView and
+// serializes each View into an rrweb-shaped wireframe snapshot with
+// coordinate conversion, background colors, extracted text, and
+// privacy auto-masking (clintplay-mask tags, password fields, and sensitive autofill hints).
+//
+// React Native's codegen emits `NativeClintplayRNSpec` from
+// `src/spec/NativeClintplayRN.ts` at build time. The TurboReactPackage
+// in `ClintplayRNPackage.kt` routes calls here.
+@ReactModule(name = ClintplayRNModule.NAME)
+class ClintplayRNModule(reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext), TurboModule {
+
+  private val mainHandler = Handler(Looper.getMainLooper())
+
+  init {
+    try {
+      resolveNativeIdResId(reactContext)
+      resolveTestIdResId(reactContext)
+    } catch (_: Throwable) {}
+  }
+
+  override fun getName(): String = NAME
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  fun getVersion(): String = VERSION
+
+  private fun formatColor(color: Int): String {
+    val alpha = (color ushr 24) and 0xFF
+    val red = (color ushr 16) and 0xFF
+    val green = (color ushr 8) and 0xFF
+    val blue = color and 0xFF
+    return String.format(java.util.Locale.US, "#%02x%02x%02x%02x", red, green, blue, alpha)
+  }
+
+  private fun extractBackgroundColor(drawable: Drawable?): String? {
+    if (drawable == null) return null
+    if (drawable is ColorDrawable) {
+      return formatColor(drawable.color)
+    }
+    val drawableClass = drawable.javaClass
+    val cached = getColorMethodCache.computeIfAbsent(drawableClass) { cls ->
+      try {
+        cls.getMethod("getColor")
+      } catch (_: Throwable) {
+        NO_METHOD_SENTINEL
+      }
+    }
+    if (cached is Method) {
+      try {
+        val colorObj = cached.invoke(drawable)
+        if (colorObj is Int) {
+          return formatColor(colorObj)
+        }
+      } catch (_: Throwable) {}
+    }
+    return null
+  }
+
+  private fun hasSensitiveAutofillHints(view: View): Boolean {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      try {
+        val hints = view.autofillHints ?: return false
+        for (hint in hints) {
+          val lower = hint.lowercase(java.util.Locale.US)
+          if (lower.contains("password") ||
+              lower.contains("creditcard") ||
+              lower.contains("credit_card") ||
+              lower.contains("otp") ||
+              lower.contains("onetimecode") ||
+              lower.contains("one_time_code") ||
+              lower.contains("cvv") ||
+              lower.contains("cvc")) {
+            return true
+          }
+        }
+      } catch (_: Throwable) {}
+    }
+    return false
+  }
+
+  private fun serializeView(
+    view: View?,
+    nodeCounter: AtomicInteger,
+    density: Float,
+    depth: Int = 0,
+  ): JSONObject? {
+    if (depth > 64) {
+      return null
+    }
+
+    if (view == null || view.visibility != View.VISIBLE || view.alpha <= 0.001f) {
+      return null
+    }
+
+    val nodeId = nodeCounter.getAndIncrement()
+    val nodeObj = JSONObject()
+    nodeObj.put("id", nodeId)
+    nodeObj.put("type", view.javaClass.simpleName)
+    nodeObj.put("className", view.javaClass.name)
+
+    // Window-relative coordinates (CAND-12)
+    val location = IntArray(2)
+    view.getLocationInWindow(location)
+
+    val safeDensity = if (density > 0f) density else 1f
+    val rawX = location[0].toDouble() / safeDensity
+    val rawY = location[1].toDouble() / safeDensity
+    val rawW = view.width.toDouble() / safeDensity
+    val rawH = view.height.toDouble() / safeDensity
+
+    val x = if (rawX.isNaN() || rawX.isInfinite()) 0.0 else round(rawX * 100.0) / 100.0
+    val y = if (rawY.isNaN() || rawY.isInfinite()) 0.0 else round(rawY * 100.0) / 100.0
+    val w = if (rawW.isNaN() || rawW.isInfinite()) 0.0 else round(rawW * 100.0) / 100.0
+    val h = if (rawH.isNaN() || rawH.isInfinite()) 0.0 else round(rawH * 100.0) / 100.0
+
+    nodeObj.put("x", x)
+    nodeObj.put("y", y)
+    nodeObj.put("width", w)
+    nodeObj.put("height", h)
+    nodeObj.put("w", w)
+    nodeObj.put("h", h)
+
+    if (view.id != View.NO_ID && view.id != 0) {
+      nodeObj.put("tag", view.id)
+    }
+
+    val bgHex = extractBackgroundColor(view.background)
+    if (bgHex != null) {
+      nodeObj.put("backgroundColor", bgHex)
+      nodeObj.put("bg", bgHex)
+    }
+
+    val nativeIdRes = resolveNativeIdResId(view.context)
+    val nativeIdTag = if (nativeIdRes != 0) view.getTag(nativeIdRes)?.toString() else null
+    val testIdRes = resolveTestIdResId(view.context)
+    val testIdTag = if (testIdRes != 0) view.getTag(testIdRes)?.toString() else null
+
+    val tagStr = view.tag?.toString()
+    val contentDesc = view.contentDescription?.toString()
+
+    val identifier = tagStr ?: nativeIdTag ?: testIdTag
+    if (!identifier.isNullOrEmpty()) {
+      nodeObj.put("accessibilityIdentifier", identifier)
+    }
+
+    val isPassword = (view is EditText && run {
+      val inputType = view.inputType
+      val inputClass = inputType and InputType.TYPE_MASK_CLASS
+      val variation = inputType and InputType.TYPE_MASK_VARIATION
+      (inputClass == InputType.TYPE_CLASS_TEXT && (
+        variation == InputType.TYPE_TEXT_VARIATION_PASSWORD ||
+        variation == InputType.TYPE_TEXT_VARIATION_WEB_PASSWORD ||
+        variation == InputType.TYPE_TEXT_VARIATION_VISIBLE_PASSWORD
+      )) || (inputClass == InputType.TYPE_CLASS_NUMBER && (
+        variation == InputType.TYPE_NUMBER_VARIATION_PASSWORD
+      ))
+    }) || (view is TextView && view.transformationMethod is PasswordTransformationMethod)
+
+    val isAutofillSensitive = hasSensitiveAutofillHints(view)
+
+    val isMasked = tagStr == "clintplay-mask" ||
+      contentDesc == "clintplay-mask" ||
+      nativeIdTag == "clintplay-mask" ||
+      testIdTag == "clintplay-mask" ||
+      isPassword ||
+      isAutofillSensitive
+
+    if (!contentDesc.isNullOrEmpty()) {
+      nodeObj.put("accessibilityLabel", if (isMasked) "***" else contentDesc)
+    }
+
+    var extractedText: String? = null
+    if (view is TextView) {
+      extractedText = view.text?.toString()
+    }
+
+    if (extractedText != null) {
+      nodeObj.put("text", if (isMasked) "***" else extractedText)
+    }
+
+    if (isMasked) {
+      nodeObj.put("masked", true)
+      nodeObj.put("children", JSONArray())
+      return nodeObj
+    }
+
+    nodeObj.put("masked", false)
+
+    val childrenArray = JSONArray()
+    if (view is ViewGroup) {
+      val childCount = view.childCount
+      for (i in 0 until childCount) {
+        val childView = view.getChildAt(i) ?: continue
+        val childJson = serializeView(childView, nodeCounter, density, depth + 1)
+        if (childJson != null) {
+          childrenArray.put(childJson)
+        }
+      }
+    }
+    nodeObj.put("children", childrenArray)
+
+    return nodeObj
+  }
+
+  private fun captureViewHierarchyOnMainThread(activity: Activity): String {
+    return try {
+      if (activity.isFinishing || activity.isDestroyed) {
+        return FALLBACK_JSON
+      }
+
+      val window = activity.window ?: return FALLBACK_JSON
+
+      // Check FLAG_SECURE (CAND-08)
+      if ((window.attributes.flags and WindowManager.LayoutParams.FLAG_SECURE) != 0) {
+        return FALLBACK_JSON
+      }
+
+      val decorView = try {
+        window.decorView
+      } catch (_: Throwable) {
+        return FALLBACK_JSON
+      } ?: return FALLBACK_JSON
+
+      val density = decorView.resources.displayMetrics.density
+      val nodeCounter = AtomicInteger(1)
+      val rootNode = serializeView(decorView, nodeCounter, density, 0)
+        ?: return FALLBACK_JSON
+
+      val ts = System.currentTimeMillis()
+      val payload = JSONObject()
+      payload.put("version", 1)
+      payload.put("ts", ts)
+      payload.put("timestamp", ts)
+
+      val nodes = JSONArray()
+      nodes.put(rootNode)
+      payload.put("nodes", nodes)
+
+      payload.toString()
+    } catch (_: Throwable) {
+      FALLBACK_JSON
+    }
+  }
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  fun captureViewHierarchy(): String {
+    val activity = currentActivity ?: return FALLBACK_JSON
+
+    if (activity.isFinishing || activity.isDestroyed) {
+      return FALLBACK_JSON
+    }
+
+    if (Looper.myLooper() == Looper.getMainLooper()) {
+      return captureViewHierarchyOnMainThread(activity)
+    }
+
+    val isCancelled = AtomicBoolean(false)
+    val result = AtomicReference(FALLBACK_JSON)
+    val latch = CountDownLatch(1)
+
+    val callback = Runnable {
+      if (isCancelled.get()) {
+        return@Runnable
+      }
+      try {
+        result.set(captureViewHierarchyOnMainThread(activity))
+      } catch (_: Throwable) {
+        result.set(FALLBACK_JSON)
+      } finally {
+        latch.countDown()
+      }
+    }
+
+    val posted = mainHandler.post(callback)
+    if (!posted) {
+      return FALLBACK_JSON
+    }
+
+    val completed = try {
+      latch.await(250, TimeUnit.MILLISECONDS)
+    } catch (_: InterruptedException) {
+      Thread.currentThread().interrupt()
+      false
+    }
+
+    if (!completed) {
+      isCancelled.set(true)
+      mainHandler.removeCallbacks(callback)
+      return FALLBACK_JSON
+    }
+
+    return result.get()
+  }
+
+  companion object {
+    const val NAME = "ClintplayRN"
+    private const val VERSION = "0.1.0"
+    private const val FALLBACK_JSON = "{\"version\":1,\"nodes\":[]}"
+
+    private val NO_METHOD_SENTINEL = Any()
+    private val getColorMethodCache = ConcurrentHashMap<Class<*>, Any>()
+
+    @Volatile
+    private var cachedNativeIdResId: Int? = null
+    @Volatile
+    private var cachedTestIdResId: Int? = null
+
+    private fun resolveNativeIdResId(context: Context): Int {
+      cachedNativeIdResId?.let { return it }
+      var id = context.resources.getIdentifier("view_tag_native_id", "id", context.packageName)
+      if (id == 0) {
+        id = context.resources.getIdentifier("view_tag_native_id", "id", "com.facebook.react")
+      }
+      cachedNativeIdResId = id
+      return id
+    }
+
+    private fun resolveTestIdResId(context: Context): Int {
+      cachedTestIdResId?.let { return it }
+      var id = context.resources.getIdentifier("react_test_id", "id", context.packageName)
+      if (id == 0) {
+        id = context.resources.getIdentifier("react_test_id", "id", "com.facebook.react")
+      }
+      cachedTestIdResId = id
+      return id
+    }
+  }
+}

package/android/src/main/java/digital/clint/clintplay/ClintplayRNPackage.kt

@@ -0,0 +1,49 @@
+package digital.clint.clintplay
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+
+// Registers the Clintplay TurboModule with the consumer's React
+// Native runtime. Supports both New Architecture (TurboModule) and
+// Old Architecture (Paper / Bridge) seamlessly.
+class ClintplayRNPackage : TurboReactPackage() {
+
+  override fun getModule(
+    name: String,
+    reactContext: ReactApplicationContext,
+  ): NativeModule? {
+    return if (name == ClintplayRNModule.NAME) {
+      ClintplayRNModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    return ReactModuleInfoProvider {
+      mapOf(
+        ClintplayRNModule.NAME to ReactModuleInfo(
+          ClintplayRNModule.NAME,
+          ClintplayRNModule::class.java.name,
+          false, // canOverrideExistingModule
+          false, // needsEagerInit
+          false, // hasConstants
+          false, // isCxxModule
+          true   // isTurboModule
+        )
+      )
+    }
+  }
+
+  override fun createNativeModules(
+    reactContext: ReactApplicationContext,
+  ): List<NativeModule> = listOf(ClintplayRNModule(reactContext))
+
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext,
+  ): List<ViewManager<*, *>> = emptyList()
+}