@ansight/react-native 1.3.0-preview.10 → 1.3.0-preview.12

package/README.md

@@ -8,6 +8,9 @@ handled by the Ansight iOS and Android SDKs. The JavaScript layer normalizes
 React Native inputs, forwards runtime calls to the native bridge, and registers
 JavaScript-backed tools for React component-tree inspection.
 
+For guarded startup and CLI verification, see the
+[React Native getting-started guide](https://www.ansight.ai/docs/sdk/react-native/setup).
+
 ## Install
 
 ### React Native CLI
@@ -36,7 +39,7 @@ npx expo install @ansight/react-native
 
 Add the bundled config plugin to the app config. It supplies the iOS camera
 usage description required by QR enrollment and the local-network description
-used when connecting to Ansight Studio:
+used when connecting to the local Ansight host:
 
 ```json
 {
@@ -45,8 +48,8 @@ used when connecting to Ansight Studio:
       [
         "@ansight/react-native",
         {
-          "cameraPermission": "Allow $(PRODUCT_NAME) to scan an Ansight Studio enrollment QR code.",
-          "localNetworkPermission": "Allow $(PRODUCT_NAME) to connect to Ansight Studio on your local network."
+          "cameraPermission": "Allow $(PRODUCT_NAME) to scan an Ansight enrollment QR code.",
+          "localNetworkPermission": "Allow $(PRODUCT_NAME) to connect to the Ansight host on your local network."
         }
       ]
     ]
@@ -77,25 +80,48 @@ bundle; its API requires the native Ansight module.
 
 This package version expects matching native SDK packages:
 
-- CocoaPods: `Ansight`, `AnsightObjC` version `1.3.0-preview.10`
-- Maven: `ai.ansight:ansight-android:1.3.0-preview.10`
+- CocoaPods: `Ansight`, `AnsightObjC` version `1.3.0-preview.12`
+- Maven: `ai.ansight:ansight-android:1.3.0-preview.12`
 
 ## Quickstart
 
 ```ts
 import Ansight from "@ansight/react-native";
 
-await Ansight.initializeAndActivate({
-  useNativeAllInOneDefaults: __DEV__,
-  clientName: "My React Native App",
-  toolGuard: __DEV__ ? "readOnly" : "disabled",
-  lifecycle: true,
-});
+let ansightStarted = false;
+
+export async function startAnsight() {
+  if (!__DEV__ || ansightStarted) {
+    return;
+  }
+  ansightStarted = true;
+
+  await Ansight.initializeAndActivate({
+    useNativeAllInOneDefaults: true,
+    clientName: "React Native App",
+    toolGuard: "readOnly",
+  });
+}
+```
+
+Call `startAnsight()` once from app bootstrap. Start the local host in one
+terminal and leave it running:
+
+```sh
+ansight host run
+```
+
+Launch the native development build, then verify the connected session and tool
+catalog from another terminal:
+
+```sh
+ansight session list --connected --json
+ansight app tools <session-id> --json
 ```
 
 The native iOS Simulator or Android emulator runtime registers automatically
-with a running, signed-in Studio. No pairing file, environment variable, host
-address, or build-time Studio probe is required.
+through loopback. No account, pairing file, environment variable, host address,
+or build-time host probe is required.
 
 `useNativeAllInOneDefaults` defaults to `false`. It only applies the native
 iOS/Android all-in-one defaults: 400 ms sampling, 120 second retention, FPS,
@@ -151,6 +177,7 @@ The TypeScript `AnsightOptions` surface mirrors Android `AnsightOptions`, iOS
 | `secureStorage` | Compatibility alias for native secure-storage allow-list settings. |
 | `remoteTools` | Native visual tree, file, database, preferences, reflection, and secure-storage tool options. |
 | `lifecycle` | JS AppState tracking toggle. Defaults to true. |
+| `networkCapture` | Opt-in `fetch` and `XMLHttpRequest` metadata capture. Accepts `true` or sanitization/capture options. |
 
 Use `withOpenFileHandleTracking()` and `withJniReferenceCountTracking()` to
 opt in through the builder. Matching `without...` methods disable the channels
@@ -201,13 +228,49 @@ await Ansight.initializeAndActivate({
 ```
 
 The touch mode captures native visual trees only on touch down and touch up.
-Move and cancel events do not trigger capture. Native touch capture and
+Move and cancel events do not trigger capture. Rapid boundaries are coalesced
+and rate-limited to protect screenshot cadence. Native touch capture and
 visual-tree tools/providers must remain enabled.
 
 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.
 
+## Network capture
+
+Network capture is explicitly enabled by the React Native layer, which
+instruments `fetch` and `XMLHttpRequest`, then sends a typed metadata record
+through the native bridge. It is opt-in:
+
+```ts
+await Ansight.initializeAndActivate(
+  Ansight.createOptionsBuilder()
+    .withAnsightDefaults()
+    .withNetworkCapture({
+      maximumBodyBytes: 64 * 1024,
+      additionalSensitiveHeaderNames: ["x-tenant-secret"],
+      additionalSensitiveQueryParameterNames: ["session"],
+      requestSanitizer: request =>
+        request.url.includes("/health") ? null : request,
+    })
+    .withoutNetworkRequestBodies() // optional, independent opt-out
+    .build(),
+);
+```
+
+Text request and response bodies are included by default after network capture
+is explicitly enabled, with a 64 KiB default per-body limit. Set a larger
+`maximumBodyBytes` when needed; use the request/response body builder methods to
+opt either side out or back in, and `captureBinaryBodies` to explicitly allow
+Base64 binary content. Standard credentials, cloud signed-URL fields, cookies,
+URL user information, and sensitive text-body assignments are redacted before
+the bridge. Capture hooks detach whenever the native host is disconnected.
+
+Use `installNetworkCapture(...)` and `uninstallNetworkCapture()` when capture
+must be controlled independently of initialization. `recordNetworkRequest(...)`
+supports custom HTTP stacks, and `sanitizeNetworkRequest(...)` exposes the same
+app-side policy for inspection or testing.
+
 ## Native Tool Options
 
 `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:
@@ -256,25 +319,19 @@ compatibility alias for `remoteTools.secureStorage`.
 
 ## Host Connection
 
-No connection call is needed for a simulator or emulator. On a physical
-device, scan the QR displayed by Studio once:
+No connection call is needed for a simulator or emulator. For a physical
+device, run `ansight pairing issue --qr`, then open the SDK scanner from a
+developer-only app surface:
 
 ```ts
 await Ansight.enrollFromQrCode({
   clientName: "My React Native App",
-  expectedAppId: "com.example.app",
 });
 ```
 
-After physical-device enrollment, `connect(null, options)` and the runtime
-connection loop use the remembered registration:
-
-```ts
-await Ansight.connect(null, { clientName: "My React Native App" });
-```
-
-When Studio is closed or signed out, automatic attempts remain dormant and
-retry later without failing the React Native app.
+The SDK supplies the native app id, stores the installation registration
+privately, and reconnects automatically on later launches. If the host is
+unavailable, retry attempts do not fail the React Native app.
 
 If the app already owns a scanner, pass its result through the explicit payload
 API:
@@ -282,17 +339,17 @@ API:
 ```ts
 await Ansight.connect(enrollmentPayload, {
   clientName: "My React Native App",
-  expectedAppId: "com.example.app",
-  hostAddressOverride: "192.168.1.20",
 });
 
 await Ansight.clearCachedSession();
 await Ansight.disconnect();
 ```
 
-`openSession(pairingPayload, options)` is the low-level direct session path.
-Prefer `connect(...)` for normal Studio sessions because it coordinates saved
-config, host auto-probe, status, telemetry, and live tool handling.
+`openSession(enrollmentPayload, options)` is the low-level direct session path.
+Prefer automatic registration for simulators and emulators or
+`enrollFromQrCode(...)` for physical devices. Use `connect(...)` only when the
+app already owns the scanner; it coordinates saved registration, host
+auto-probe, status, telemetry, and live tool handling.
 
 ## Runtime API
 
@@ -302,7 +359,7 @@ The bridge exposes the native SDK runtime surface:
 | --- | --- |
 | `initialize`, `initializeAndActivate`, `activate`, `deactivate`, `clear` | Runtime lifecycle. |
 | `connect`, `disconnect`, `openSession`, `completeSession`, `closeSession` | Host and live-session control. |
-| `savePairingConfig`, `clearSavedPairing`, `clearCachedSession` | Pairing persistence. |
+| `clearCachedSession` | Clears remembered app-installation registration state. |
 | `status`, `snapshot`, `hostConnectionStatus`, `currentOptions` | Diagnostics and state. |
 | `registerMetricChannel`, `metric`, `recordMetric` | Metric channels and samples. |
 | `event`, `recordEvent`, `screenViewed`, `trackRoute` | App events and screen views. |
@@ -389,6 +446,19 @@ await Ansight.clearSessionProperties();
 When connected, property mutations are sent immediately. When disconnected, the
 latest values are included in the next `session.open`.
 
+The bridge automatically adds these property groups:
+
+| Group | Properties |
+| --- | --- |
+| `reactNative` | Ansight SDK, React Native and React versions; platform and runtime language; JavaScript engine and available Hermes version/bytecode details; legacy/new architecture; bridgeless state; development mode. |
+| `localization` | Canonical locale, language, optional region, IANA time zone when exposed by `Intl`, and UTC offset in minutes. |
+
+App-provided values override an automatic value with the same group and key.
+Clearing all properties, or removing one automatic property, restores the
+current bridge-owned value. `localization` reflects the JavaScript runtime
+locale; if the app selects a different language through an i18n library, set
+`localization.locale`, `language`, and `region` explicitly.
+
 ## Tool Guards
 
 | Value | Allowed scopes |

package/android/build.gradle

@@ -67,6 +67,6 @@ repositories {
 dependencies {
   implementation("com.facebook.react:react-android")
   def ansightAndroidVersion =
-      findProperty("ansightAndroidVersion") ?: "1.3.0-preview.10"
-  implementation("ai.ansight:ansight-android:1.3.0-preview.10")
+      findProperty("ansightAndroidVersion") ?: "1.3.0-preview.12"
+  implementation("ai.ansight:ansight-android:1.3.0-preview.12")
 }

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

@@ -12,6 +12,7 @@ import ai.ansight.runtime.AnsightHostConnectionOptions
 import ai.ansight.runtime.AnsightLogCallback
 import ai.ansight.runtime.AnsightLogLevel
 import ai.ansight.runtime.AnsightLogger
+import ai.ansight.runtime.AnsightNetworkRequest
 import ai.ansight.runtime.AnsightOptions
 import ai.ansight.runtime.AnsightOptionsBuilder
 import ai.ansight.runtime.AnsightRuntime
@@ -28,6 +29,7 @@ import ai.ansight.runtime.HostConnectionRequestKind
 import ai.ansight.runtime.HostConnectionCapabilities
 import ai.ansight.runtime.HostConnectionResult
 import ai.ansight.runtime.HostConnectionStatus
+import ai.ansight.runtime.HostConnectionStatusSubscription
 import ai.ansight.runtime.OperationResult
 import ai.ansight.runtime.OpenSessionResult
 import ai.ansight.runtime.PairingOpenOptions
@@ -104,16 +106,21 @@ class AnsightReactNativeModule(
     private val logCallback = AnsightLogCallback { level, message, throwable ->
         emitLogEvent(level, message, throwable)
     }
+    private val hostConnectionStatusSubscription: HostConnectionStatusSubscription
 
     init {
         reactContext.addLifecycleEventListener(this)
         AnsightLogger.registerCallback(logCallback)
+        hostConnectionStatusSubscription = AnsightRuntime.addHostConnectionStatusListener(
+            listener = { status, _ -> emitHostConnectionStatusEvent(status) },
+        )
     }
 
     override fun getName(): String = "AnsightReactNative"
 
     override fun invalidate() {
         AnsightLogger.removeCallback(logCallback)
+        hostConnectionStatusSubscription.remove()
         reactContext.removeLifecycleEventListener(this)
         super.invalidate()
     }
@@ -226,6 +233,17 @@ class AnsightReactNativeModule(
         }.resolve(promise)
     }
 
+    @ReactMethod
+    fun recordNetworkRequest(input: ReadableMap, promise: Promise) {
+        runCatching {
+            val request = AnsightNetworkRequest.fromJson(JSONObject(input.toHashMap()))
+                ?: return@runCatching operationResultMap(
+                    OperationResult.failure("Network request must use the ansight.network-request.v1 schema."),
+                )
+            operationResultMap(AnsightRuntime.recordNetworkRequest(request))
+        }.resolve(promise)
+    }
+
     @ReactMethod
     fun recordCrashCandidate(input: ReadableMap, promise: Promise) {
         runCatching {
@@ -677,6 +695,16 @@ class AnsightReactNativeModule(
         }
     }
 
+    private fun emitHostConnectionStatusEvent(status: HostConnectionStatus) {
+        if (listenerCount.get() <= 0) return
+        val event = hostConnectionStatusMap(status)
+        UiThreadUtil.runOnUiThread {
+            reactContext
+                .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                .emit("AnsightHostConnectionStatus", event)
+        }
+    }
+
     private fun configureReactNativeMemoryProfiling(map: ReadableMap?) {
         val options = reactNativeMemoryProfilingOptions(map)
         currentReactNativeMemoryOptions = options

package/index.d.ts

@@ -48,6 +48,75 @@ export interface AnsightTouchCaptureOptions {
   moveCaptureFramesPerSecond?: number;
 }
 
+export interface AnsightNetworkHeader {
+  name: string;
+  value: string;
+}
+
+export interface AnsightNetworkBody {
+  contentType?: string;
+  encoding: "utf8" | "base64";
+  data: string;
+  capturedBytes: number;
+  totalBytes?: number;
+  truncated: boolean;
+}
+
+/** V1 network metadata with optional, bounded bodies. */
+export interface AnsightNetworkRequest {
+  schema: "ansight.network-request.v1";
+  id: string;
+  source: string;
+  startedAtUtc: string;
+  completedAtUtc: string;
+  durationMilliseconds: number;
+  method: string;
+  url: string;
+  protocol?: string;
+  requestHeaders: AnsightNetworkHeader[];
+  requestBodySizeBytes?: number;
+  requestBody?: AnsightNetworkBody;
+  statusCode?: number;
+  reasonPhrase?: string;
+  responseHeaders: AnsightNetworkHeader[];
+  responseBodySizeBytes?: number;
+  responseBody?: AnsightNetworkBody;
+  errorType?: string;
+  errorMessage?: string;
+}
+
+export type AnsightNetworkRequestInput = Partial<AnsightNetworkRequest> & {
+  method: string;
+  url: string;
+};
+
+export interface AnsightNetworkSanitizationOptions {
+  includeRequestHeaders?: boolean;
+  includeResponseHeaders?: boolean;
+  includeQueryString?: boolean;
+  includeBodySizes?: boolean;
+  /** Defaults to true. */
+  captureRequestBody?: boolean;
+  /** Defaults to true. */
+  captureResponseBody?: boolean;
+  /** Decoded bytes retained per body. Defaults to 64 KiB; larger explicit limits are honored. */
+  maximumBodyBytes?: number;
+  captureBinaryBodies?: boolean;
+  additionalSensitiveHeaderNames?: string[];
+  additionalSensitiveQueryParameterNames?: string[];
+  urlSanitizer?: (url: string) => string;
+  /** Return a replacement request, or null to suppress capture. */
+  requestSanitizer?: (
+    request: AnsightNetworkRequest,
+  ) => AnsightNetworkRequest | null;
+}
+
+export interface AnsightNetworkCaptureOptions
+  extends AnsightNetworkSanitizationOptions {
+  captureFetch?: boolean;
+  captureXmlHttpRequest?: boolean;
+}
+
 export interface AnsightNativeToolRoot {
   alias: string;
   path: string;
@@ -155,6 +224,8 @@ export interface AnsightOptions {
   remoteTools?: AnsightRemoteToolsOptions;
   additionalChannels?: AnsightChannel[];
   lifecycle?: boolean;
+  /** Explicitly opt in to fetch/XMLHttpRequest instrumentation. */
+  networkCapture?: boolean | AnsightNetworkCaptureOptions;
 }
 
 export interface AnsightCrashCaptureOptions {
@@ -300,6 +371,12 @@ export class AnsightOptionsBuilder {
   withCrashCapture(crashCapture?: AnsightCrashCaptureOptions): this;
   withoutCrashCapture(): this;
   withLifecycleCapture(lifecycleCapture?: NonNullable<AnsightOptions["lifecycleCapture"]>): this;
+  withNetworkCapture(networkCapture?: AnsightNetworkCaptureOptions): this;
+  withNetworkRequestBodies(maximumBodyBytes?: number): this;
+  withoutNetworkRequestBodies(): this;
+  withNetworkResponseBodies(maximumBodyBytes?: number): this;
+  withoutNetworkResponseBodies(): this;
+  withoutNetworkCapture(): this;
   withToolGuard(toolGuard: NonNullable<AnsightOptions["toolGuard"]>): this;
   withToolsDisabled(): this;
   withReadOnlyToolAccess(): this;
@@ -543,6 +620,18 @@ export function recordMetric(value: number, channel?: number): Promise<AnsightDe
 export function event(input: string | { label: string; type?: string; details?: string; channel?: number }): Promise<AnsightDebugSnapshot>;
 export function recordEvent(input: string | { label: string; type?: string; details?: string; channel?: number }): Promise<AnsightDebugSnapshot>;
 export function recordCrashCandidate(input?: AnsightCrashCandidate): Promise<{ candidateId?: string }>;
+export function recordNetworkRequest(
+  input: AnsightNetworkRequestInput,
+  sanitizationOptions?: AnsightNetworkSanitizationOptions,
+): Promise<AnsightOperationResult>;
+export function sanitizeNetworkRequest(
+  input: AnsightNetworkRequestInput,
+  sanitizationOptions?: AnsightNetworkSanitizationOptions,
+): AnsightNetworkRequest | null;
+export function installNetworkCapture(
+  options?: AnsightNetworkCaptureOptions,
+): AnsightSubscription;
+export function uninstallNetworkCapture(): void;
 export function screenViewed(name: string, details?: Record<string, string>): Promise<AnsightDebugSnapshot>;
 export function trackRoute(name: string, details?: Record<string, string>): Promise<AnsightDebugSnapshot>;
 export function setAppLifecycleState(state: AnsightLifecycleState): Promise<AnsightDebugSnapshot>;
@@ -617,6 +706,7 @@ declare const Ansight: {
   event: typeof event;
   recordEvent: typeof recordEvent;
   recordCrashCandidate: typeof recordCrashCandidate;
+  recordNetworkRequest: typeof recordNetworkRequest;
   screenViewed: typeof screenViewed;
   trackRoute: typeof trackRoute;
   setAppLifecycleState: typeof setAppLifecycleState;
@@ -671,6 +761,9 @@ declare const Ansight: {
   installReactTools: typeof installReactTools;
   uninstallReactTools: typeof uninstallReactTools;
   installErrorHandlers: typeof installErrorHandlers;
+  installNetworkCapture: typeof installNetworkCapture;
+  uninstallNetworkCapture: typeof uninstallNetworkCapture;
+  sanitizeNetworkRequest: typeof sanitizeNetworkRequest;
   createReactNavigationTracker: typeof createReactNavigationTracker;
   platform: "ios" | "android" | string;
 };