@ansight/react-native 1.0.2-preview.1 → 1.0.2-preview.3

package/README.md

@@ -25,8 +25,8 @@ npx react-native run-android
 
 This package version expects matching native SDK packages:
 
-- CocoaPods: `Ansight`, `AnsightObjC` version `1.0.2-preview.1`
-- Maven: `ai.ansight:ansight-android:1.0.2-preview.1`
+- CocoaPods: `Ansight`, `AnsightObjC` version `1.0.2-preview.3`
+- Maven: `ai.ansight:ansight-android:1.0.2-preview.3`
 
 ## Quickstart
 
@@ -38,6 +38,13 @@ const isDevelopmentOnly = __DEV__;
 await Ansight.initializeAndActivate({
   useNativeAllInOneDefaults: isDevelopmentOnly,
   clientName: "My React Native App",
+  hostAutoProbe: {
+    enabled: isDevelopmentOnly,
+    initialDelayMilliseconds: 1000,
+    probeIntervalMilliseconds: 5000,
+    reconnectDelayMilliseconds: 10000,
+    clientName: "My React Native App",
+  },
   hostConnection: isDevelopmentOnly ? {
     bundledDeveloperConfigJson: process.env.EXPO_PUBLIC_ANSIGHT_PAIRING_CONFIG_JSON,
   } : undefined,
@@ -59,6 +66,19 @@ does not infer whether the app is a debug build. Gate it with the app's own
 condition, such as React Native's `__DEV__`, and configure `toolGuard`, capture
 options, host auto-probe, and host connection separately.
 
+Host auto-probe uses the native iOS/Android remembered-host retry behavior.
+When enabled and the runtime is active, it retries previous host connections so
+the app can reconnect after the host disappears and later reappears. Probing
+pauses while a live session is connected and resumes after
+`reconnectDelayMilliseconds` when that session is lost. Use
+`withoutHostAutoProbe()` or set `hostAutoProbe.enabled` to `false` for flows
+where reconnects should only happen after an explicit app action.
+
+> **Important:** Screen capture will result in an FPS drop while native frames
+> are rendered, encoded, and sent. Use conservative interval, quality, and
+> max-width settings, and disable `sessionJpegCapture` for performance-focused
+> runs unless visual evidence is required.
+
 ## Options
 
 The TypeScript `AnsightOptions` surface mirrors Android `AnsightOptions`, iOS
@@ -66,7 +86,7 @@ The TypeScript `AnsightOptions` surface mirrors Android `AnsightOptions`, iOS
 
 | Option | Purpose |
 | --- | --- |
-| `useNativeAllInOneDefaults` | Applies native iOS/Android all-in-one defaults when true. Defaults to false. This is not a master enable switch; configure `toolGuard`, capture options, and `hostConnection` separately. |
+| `useNativeAllInOneDefaults` | Applies native iOS/Android all-in-one defaults when true. Defaults to false. This enables the native visual-tree/screenshot tools required by Studio visual tree inspection unless `remoteTools.visualTree` is explicitly false. Configure `toolGuard`, capture options, and `hostConnection` separately. |
 | `pairingConfigJson` | Legacy top-level pairing JSON. Prefer `hostConnection.*`. |
 | `clientName` | Default client name for host auto-probe and connections. |
 | `sampleFrequencyMilliseconds` | Built-in telemetry sampling interval. |
@@ -76,12 +96,12 @@ The TypeScript `AnsightOptions` surface mirrors Android `AnsightOptions`, iOS
 | `defaultMemoryChannels` | Selects built-in memory channels. Prefer `managedHeap`, `nativeHeap`, `residentSetSize`, and `physicalFootprint`; `javaHeap` and `rss` are accepted as Android/RN compatibility aliases. |
 | `reactNativeMemory` | Controls native React Native runtime memory channels. Enabled by default; set to `false` to disable, or use `{ jsHeapUsed, jsHeapTotal }`. |
 | `additionalChannels` | Registers custom metric channels. |
-| `sessionJpegCapture` | Object to enable/configure capture, or `false` to disable. |
+| `sessionJpegCapture` | Object to enable/configure capture, or `false` to disable. Supports `captureGpuBackedSurfaces`; on iOS it defaults to `true` so Metal, SceneKit, and similar GPU-backed views are included. |
 | `touchCapture` | Object to enable/configure capture, or `false` to disable. |
 | `lifecycleCapture` | Native lifecycle and screen-view capture options. |
 | `toolGuard` | `"disabled"`, `"readOnly"`, `"readWrite"`, or `"fullAccess"`. |
 | `customProperties` | Grouped string properties sent with `session.open`. |
-| `hostAutoProbe` | Automatic host reconnect loop settings. |
+| `hostAutoProbe` | Remembered-host retry settings for reconnecting after the host disappears and later reappears. |
 | `hostConnection` | Saved, bundled, and developer pairing settings. |
 | `secureStorage` | Compatibility alias for native secure-storage allow-list settings. |
 | `remoteTools` | Native visual tree, file, database, preferences, reflection, and secure-storage tool options. |
@@ -97,6 +117,7 @@ await Ansight.initializeAndActivate({
     intervalMilliseconds: 2000,
     quality: 60,
     maxWidth: 480,
+    captureGpuBackedSurfaces: true,
   },
   touchCapture: {
     captureMoveEvents: true,
@@ -106,14 +127,21 @@ await Ansight.initializeAndActivate({
   },
   hostAutoProbe: {
     enabled: true,
+    initialDelayMilliseconds: 1000,
+    probeIntervalMilliseconds: 5000,
+    reconnectDelayMilliseconds: 10000,
     clientName: "My React Native App",
   },
 });
 ```
 
+On iOS, `captureGpuBackedSurfaces` defaults to `true` so Metal, SceneKit, and
+similar GPU-backed views are included. Set it to `false` to use a lower-overhead
+capture path when those surfaces are not needed.
+
 ## Native Tool Options
 
-`remoteTools` configures the native tool suites registered by the bridge. Visual tree tools are opt-in:
+`remoteTools` configures the native tool suites registered by the bridge. `useNativeAllInOneDefaults: true` enables visual tree tools by default so Studio can pair `ui.get_visual_tree` data with `ui.get_screenshot` frames. Apps that do not use all-in-one defaults can opt in explicitly:
 
 ```ts
 await Ansight.initializeAndActivate(
@@ -147,6 +175,12 @@ await Ansight.initializeAndActivate(
 );
 ```
 
+`reflect.list_roots` reports a `hostRuntime` descriptor on each root. Current
+React Native reflection roots are hosted by the native iOS or Android runtime;
+future JavaScript reflection roots should report `kind: "javascript"` and
+`bridge: "react-native"` so callers can route reflection requests to the
+correct runtime boundary.
+
 `secureStorage.preferencesName` is Android-specific. `secureStorage.appleService`
 is iOS-specific. The top-level `secureStorage` option is still accepted as a
 compatibility alias for `remoteTools.secureStorage`.
@@ -165,7 +199,7 @@ await Ansight.connect(null, {
 Automatic connection tries:
 
 1. `hostConnection.bundledDeveloperConfigJson`
-2. native cached host profiles where implemented
+2. native remembered host profiles, newest first
 3. saved pairing config
 4. `hostConnection.bundledConfigJson`
 
@@ -406,7 +440,11 @@ const snapshot = await Ansight.snapshot();
 const options = await Ansight.currentOptions();
 
 await Ansight.captureBuiltInTelemetrySample();
-await Ansight.captureScreenFrame({ quality: 60, maxWidth: 480 });
+await Ansight.captureScreenFrame({
+  quality: 60,
+  maxWidth: 480,
+  captureGpuBackedSurfaces: true,
+});
 await Ansight.enableTouchCapture();
 await Ansight.disableTouchCapture();
 ```

package/android/build.gradle

@@ -66,5 +66,5 @@ repositories {
 
 dependencies {
   implementation("com.facebook.react:react-android")
-  implementation("ai.ansight:ansight-android:1.0.2-preview.1")
+  implementation("ai.ansight:ansight-android:1.0.2-preview.3")
 }

package/android/src/main/kotlin/ai/ansight/reactnative/AnsightReactNativeModule.kt

@@ -702,6 +702,10 @@ class AnsightReactNativeModule(
                         ),
                         quality = jpeg.intValue("quality", AnsightSessionJpegCaptureOptions.DefaultQuality),
                         maxWidth = jpeg.optionalInt("maxWidth") ?: AnsightSessionJpegCaptureOptions.DefaultMaxWidth,
+                        captureGpuBackedSurfaces = jpeg.booleanValue(
+                            "captureGpuBackedSurfaces",
+                            AnsightSessionJpegCaptureOptions.DefaultCaptureGpuBackedSurfaces,
+                        ),
                     )
                 },
             )
@@ -762,13 +766,19 @@ class AnsightReactNativeModule(
                 ),
             )
         }
-        return options.withNativeToolOptions(map)
+        return options.withNativeToolOptions(
+            map,
+            enableVisualTreeToolsByDefault = useNativeAllInOneDefaults,
+        )
     }
 
-    private fun AnsightOptions.withNativeToolOptions(map: ReadableMap?): AnsightOptions {
+    private fun AnsightOptions.withNativeToolOptions(
+        map: ReadableMap?,
+        enableVisualTreeToolsByDefault: Boolean,
+    ): AnsightOptions {
         val remoteTools = map.getMapOrNull("remoteTools")
         val builder = AnsightOptions.createBuilder(this)
-        if (remoteTools.toolSuiteEnabled("visualTree")) {
+        if (remoteTools.toolSuiteEnabled("visualTree", enableVisualTreeToolsByDefault)) {
             builder.withVisualTreeTools()
         }
         builder.withDatabaseTools(databaseToolsOptions(remoteTools.getMapOrNull("database")))
@@ -868,6 +878,10 @@ class AnsightReactNativeModule(
             ),
             quality = map.intValue("quality", AnsightSessionJpegCaptureOptions.DefaultQuality),
             maxWidth = map.optionalInt("maxWidth") ?: AnsightSessionJpegCaptureOptions.DefaultMaxWidth,
+            captureGpuBackedSurfaces = map.booleanValue(
+                "captureGpuBackedSurfaces",
+                AnsightSessionJpegCaptureOptions.DefaultCaptureGpuBackedSurfaces,
+            ),
         )
     }
 
@@ -1058,6 +1072,7 @@ class AnsightReactNativeModule(
                     "intervalMilliseconds" to capture.intervalMilliseconds,
                     "quality" to capture.quality,
                     "maxWidth" to capture.maxWidth,
+                    "captureGpuBackedSurfaces" to capture.captureGpuBackedSurfaces,
                 ).toWritableMap())
             } ?: putNull("sessionJpegCapture")
             options.touchCapture?.let { touch ->
@@ -1206,9 +1221,12 @@ private fun ReadableMap?.hasBoolean(name: String): Boolean = this?.hasKey(name)
 private fun ReadableMap?.hasMap(name: String): Boolean = this?.hasKey(name) == true && this.getType(name) == ReadableType.Map
 private fun ReadableMap?.hasArray(name: String): Boolean = this?.hasKey(name) == true && this.getType(name) == ReadableType.Array
 private fun ReadableMap?.isFalse(name: String): Boolean = this?.hasBoolean(name) == true && !this.getBoolean(name)
-private fun ReadableMap?.toolSuiteEnabled(name: String): Boolean {
-    val map = this ?: return false
-    if (!map.hasKey(name) || map.isNull(name)) {
+private fun ReadableMap?.toolSuiteEnabled(name: String, defaultValue: Boolean = false): Boolean {
+    val map = this ?: return defaultValue
+    if (!map.hasKey(name)) {
+        return defaultValue
+    }
+    if (map.isNull(name)) {
         return false
     }
     return when (map.getType(name)) {

package/index.d.ts

@@ -36,6 +36,7 @@ export interface AnsightSessionJpegCaptureOptions {
   intervalMilliseconds?: number;
   quality?: number;
   maxWidth?: number;
+  captureGpuBackedSurfaces?: boolean;
 }
 
 export interface AnsightTouchCaptureOptions {
@@ -261,7 +262,12 @@ export class AnsightOptionsBuilder {
   withReactNativeMemoryProfiling(options?: AnsightReactNativeMemoryOptions): this;
   withoutReactNativeMemoryProfiling(): this;
   withSessionJpegCapture(options?: AnsightSessionJpegCaptureOptions): this;
-  withSessionJpegCapture(intervalMilliseconds: number, quality?: number, maxWidth?: number | null): this;
+  withSessionJpegCapture(
+    intervalMilliseconds: number,
+    quality?: number,
+    maxWidth?: number | null,
+    captureGpuBackedSurfaces?: boolean
+  ): this;
   withoutSessionJpegCapture(): this;
   withTouchCapture(touchCapture?: AnsightTouchCaptureOptions): this;
   withoutTouchCapture(): this;

package/index.js

@@ -267,6 +267,7 @@ class AnsightOptionsBuilder {
         intervalMilliseconds: optionsOrIntervalMilliseconds,
         quality: arguments.length > 1 ? arguments[1] : 60,
         maxWidth: arguments.length > 2 ? arguments[2] : 480,
+        captureGpuBackedSurfaces: arguments.length > 3 ? arguments[3] : true,
       };
       return this;
     }

package/ios/AnsightReactNative.swift

@@ -925,7 +925,12 @@ final class AnsightReactNative: RCTEventEmitter {
                         defaultValue: AnsightSessionJpegCaptureOptions.defaultIntervalMilliseconds
                     ),
                     quality: intValue(jpeg, "quality", defaultValue: AnsightSessionJpegCaptureOptions.defaultQuality),
-                    maxWidth: optionalInt(jpeg, "maxWidth") ?? AnsightSessionJpegCaptureOptions.defaultMaxWidth
+                    maxWidth: optionalInt(jpeg, "maxWidth") ?? AnsightSessionJpegCaptureOptions.defaultMaxWidth,
+                    captureGpuBackedSurfaces: boolValue(
+                        jpeg,
+                        "captureGpuBackedSurfaces",
+                        defaultValue: AnsightSessionJpegCaptureOptions.defaultCaptureGpuBackedSurfaces
+                    )
                 )
             }
         }
@@ -982,8 +987,12 @@ final class AnsightReactNative: RCTEventEmitter {
 
     private func remoteToolOptions(_ dictionary: NSDictionary?) -> AnsightRemoteToolOptions {
         let remoteTools = dictionary?["remoteTools"] as? NSDictionary
+        let useNativeAllInOneDefaults = boolValue(dictionary, "useNativeAllInOneDefaults", defaultValue: false)
         return AnsightRemoteToolOptions(
-            visualTree: toolSuiteEnabled(remoteTools?["visualTree"]),
+            visualTree: toolSuiteEnabled(
+                remoteTools?["visualTree"],
+                defaultValue: useNativeAllInOneDefaults
+            ),
             database: databaseToolsOptions(remoteTools?["database"] as? NSDictionary),
             fileSystem: fileSystemToolsOptions(remoteTools?["fileSystem"] as? NSDictionary),
             preferences: preferencesToolsOptions(remoteTools?["preferences"] as? NSDictionary),
@@ -994,14 +1003,14 @@ final class AnsightReactNative: RCTEventEmitter {
         )
     }
 
-    private func toolSuiteEnabled(_ value: Any?) -> Bool {
+    private func toolSuiteEnabled(_ value: Any?, defaultValue: Bool = false) -> Bool {
         if let enabled = value as? Bool {
             return enabled
         }
         if let dictionary = value as? NSDictionary {
             return boolValue(dictionary, "enabled", defaultValue: true)
         }
-        return false
+        return defaultValue
     }
 
     private func fileSystemToolsOptions(_ dictionary: NSDictionary?) -> AnsightFileSystemToolsOptions {
@@ -1241,7 +1250,12 @@ final class AnsightReactNative: RCTEventEmitter {
                 defaultValue: AnsightSessionJpegCaptureOptions.defaultIntervalMilliseconds
             ),
             quality: intValue(dictionary, "quality", defaultValue: AnsightSessionJpegCaptureOptions.defaultQuality),
-            maxWidth: optionalInt(dictionary, "maxWidth") ?? AnsightSessionJpegCaptureOptions.defaultMaxWidth
+            maxWidth: optionalInt(dictionary, "maxWidth") ?? AnsightSessionJpegCaptureOptions.defaultMaxWidth,
+            captureGpuBackedSurfaces: boolValue(
+                dictionary,
+                "captureGpuBackedSurfaces",
+                defaultValue: AnsightSessionJpegCaptureOptions.defaultCaptureGpuBackedSurfaces
+            )
         )
     }
 
@@ -1289,6 +1303,7 @@ final class AnsightReactNative: RCTEventEmitter {
                 "intervalMilliseconds": capture.intervalMilliseconds,
                 "quality": capture.quality,
                 "maxWidth": capture.maxWidth as Any,
+                "captureGpuBackedSurfaces": capture.captureGpuBackedSurfaces,
             ]
         } else {
             dictionary["sessionJpegCapture"] = NSNull()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansight/react-native",
-  "version": "1.0.2-preview.1",
+  "version": "1.0.2-preview.3",
   "description": "React Native bridge for the Ansight mobile SDK.",
   "main": "index.js",
   "types": "index.d.ts",