@ansight/react-native 1.0.2-preview.1

package/AnsightReactNative.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "AnsightReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://github.com/ansight-ai/ansight-sdk"
+  s.license      = { :type => "Ansight SDK Source-Available License", :file => "LICENSE" }
+  s.authors      = { "Ansight" => "dev@ansight.ai" }
+  s.source       = { :path => "." }
+  s.platforms    = { :ios => "15.0" }
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.dependency "React-Core"
+  s.dependency "React-jsi"
+  s.dependency "AnsightObjC", s.version.to_s
+  s.dependency "Ansight", s.version.to_s
+  s.swift_version = "5.0"
+end

package/LICENSE

@@ -0,0 +1,200 @@
+Ansight SDK Source-Available License
+Version 1.0
+
+Copyright (c) 2026 Ansight, Inc. All rights reserved.
+
+This license governs the Ansight SDK and associated source code, documentation,
+examples, build files, binaries, and other materials made available with it
+(the "SDK").
+
+The SDK is source-available software. It is not open-source software.
+
+By downloading, installing, copying, modifying, distributing, or using the SDK,
+you accept this license. If you do not accept this license, you may not use the
+SDK.
+
+1. Purpose
+
+Ansight makes the SDK source available so developers, customers, researchers,
+and security reviewers can inspect how the SDK works, evaluate its security,
+debug integrations, report issues, and propose improvements.
+
+Except for the rights expressly granted below, Ansight reserves all rights.
+
+2. Definitions
+
+"Ansight Services" means services, APIs, systems, products, accounts,
+infrastructure, software, development tools, test endpoints, sandbox
+environments, local tools, or other components operated by, provided by,
+authorized by, or on behalf of Ansight, Inc. or its affiliates. This includes
+Ansight-hosted services, Ansight Studio, Ansight APIs, Ansight-issued accounts
+or API keys, and any service or component expressly authorized by Ansight in
+writing.
+
+"Non-Ansight Services" means any service, API, backend, product, infrastructure,
+system, software, or component that is not an Ansight Service.
+
+"Application" means software developed by you that incorporates, links to, or
+uses the SDK.
+
+3. Permitted Uses
+
+Subject to this license, you may:
+
+(a) read, inspect, and analyze the SDK source code;
+
+(b) copy and build the SDK for evaluation, testing, debugging, security review,
+and development of Applications that use Ansight Services;
+
+(c) modify the SDK for your own internal development, testing, debugging,
+security review, or use with Ansight Services;
+
+(d) use and distribute the SDK, including in source, compiled, or object-code
+form, only as part of an Application that connects to or interoperates with
+Ansight Services;
+
+(e) distribute Applications containing the SDK through app stores, package
+managers, enterprise distribution systems, mobile device management systems,
+continuous integration systems, TestFlight, Google Play testing tracks, or
+similar software distribution channels, provided the SDK is used only with
+Ansight Services;
+
+(f) share bug reports, vulnerability reports, patches, pull requests, and other
+proposed improvements with Ansight; and
+
+(g) make public forks or copies of the SDK solely for review, discussion,
+security research, issue reporting, or contribution back to Ansight, provided
+that this license and all copyright, trademark, attribution, and other notices
+remain intact.
+
+4. Restrictions
+
+You may not:
+
+(a) use the SDK with, connect the SDK to, or adapt the SDK for any Non-Ansight
+Services;
+
+(b) use the SDK to develop, operate, enable, or support any service or product
+that replaces, proxies, emulates, competes with, or avoids the need for Ansight
+Services;
+
+(c) sell, sublicense, rent, lease, host, or provide the SDK as a standalone
+product, SDK-as-a-service, managed service, hosted service, or competing SDK
+distribution;
+
+(d) remove, obscure, or alter any copyright, license, trademark, attribution,
+security, telemetry, pairing, provenance, or service-association notices in the
+SDK;
+
+(e) circumvent license checks, authentication, pairing, service association,
+security controls, or technical measures in the SDK or Ansight Services;
+
+(f) use Ansight names, logos, or trademarks except as necessary to accurately
+identify the SDK or Ansight Services;
+
+(g) use the SDK in violation of applicable law, regulation, sanctions,
+export-control rules, privacy rules, app-store policies, or third-party rights;
+or
+
+(h) grant any rights in the SDK to others beyond the rights expressly permitted
+by this license.
+
+5. Contributions
+
+If you submit a patch, pull request, issue comment, vulnerability report, code,
+documentation, suggestion, or other contribution to Ansight relating to the SDK,
+you grant Ansight a perpetual, worldwide, irrevocable, sublicensable,
+transferable, royalty-free license to use, reproduce, modify, distribute,
+perform, display, commercialize, and otherwise exploit that contribution for any
+purpose.
+
+You represent that you have the right to grant this license for your
+contribution.
+
+To the extent permitted by law, you waive and agree not to assert moral rights
+in your contribution against Ansight, its affiliates, its customers, or its
+users.
+
+6. Security Research
+
+Ansight welcomes good-faith security review of the SDK. You may inspect, test,
+and analyze the SDK for security issues and disclose suspected vulnerabilities
+to Ansight through the security reporting process published by Ansight.
+
+This license does not authorize access to systems, services, accounts, devices,
+networks, data, or infrastructure without permission. It does not authorize
+disruption, degradation, data exfiltration, privacy violations, or activity that
+would harm Ansight, its customers, or third parties.
+
+7. Separate Agreements
+
+If you have a separate written agreement with Ansight governing your use of the
+SDK, that agreement controls to the extent of any conflict with this license.
+
+8. Third-Party Software
+
+The SDK may include or depend on third-party software, libraries, tools, or
+materials. Those components are licensed under their own terms. This license
+applies only to the SDK materials provided by Ansight.
+
+9. No Support Obligation
+
+Ansight has no obligation under this license to provide support, maintenance,
+updates, hosted services, compatibility fixes, security fixes, or other
+assistance for the SDK.
+
+10. Trademarks
+
+No trademark rights are granted under this license. You may use Ansight names
+only as necessary to accurately identify the SDK or Ansight Services, and only
+in a way that does not imply endorsement, sponsorship, or affiliation except as
+expressly authorized by Ansight.
+
+11. Termination
+
+If you violate this license, your rights under it terminate automatically. Upon
+termination, you must stop using, copying, modifying, and distributing the SDK.
+
+Sections 4 through 18 survive termination.
+
+12. No Warranty
+
+The SDK is provided "as is" and "as available", without warranties or conditions
+of any kind, whether express, implied, statutory, or otherwise, including
+warranties of merchantability, fitness for a particular purpose, title,
+non-infringement, security, accuracy, availability, or error-free operation.
+
+13. Limitation of Liability
+
+To the maximum extent permitted by law, Ansight will not be liable for any
+indirect, incidental, special, consequential, exemplary, or punitive damages, or
+for lost profits, lost revenues, lost data, loss of goodwill, business
+interruption, security incidents, or service interruption, arising out of or
+relating to the SDK or this license.
+
+14. Assignment
+
+You may not assign or transfer this license without Ansight's prior written
+consent. Ansight may assign or transfer this license without restriction.
+
+15. Waiver
+
+Failure by Ansight to enforce any provision of this license does not waive its
+right to enforce that provision or any other provision later.
+
+16. Severability
+
+If any provision of this license is found unenforceable, the remaining
+provisions remain in effect, and the unenforceable provision will be interpreted
+to the maximum extent permitted by law.
+
+17. Entire Agreement
+
+This license is the entire agreement between you and Ansight regarding the SDK,
+except to the extent you have a separate written agreement with Ansight that
+controls under Section 7.
+
+18. No Other Rights
+
+No rights are granted except as expressly stated in this license. All rights not
+expressly granted are reserved by Ansight.

package/README.md

@@ -0,0 +1,436 @@
+# @ansight/react-native
+
+React Native bridge for the Ansight mobile SDK.
+
+The package is intentionally thin: pairing, transport, telemetry, screen
+capture, touch capture, native tool discovery, and native tool execution are
+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.
+
+## Install
+
+```sh
+npm install @ansight/react-native
+```
+
+Rebuild the native app so React Native autolinking installs the iOS pod and
+Android library module:
+
+```sh
+npx pod-install
+npx react-native run-ios
+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`
+
+## Quickstart
+
+```ts
+import Ansight from "@ansight/react-native";
+
+const isDevelopmentOnly = __DEV__;
+
+await Ansight.initializeAndActivate({
+  useNativeAllInOneDefaults: isDevelopmentOnly,
+  clientName: "My React Native App",
+  hostConnection: isDevelopmentOnly ? {
+    bundledDeveloperConfigJson: process.env.EXPO_PUBLIC_ANSIGHT_PAIRING_CONFIG_JSON,
+  } : undefined,
+  toolGuard: isDevelopmentOnly ? "readOnly" : "disabled",
+  lifecycle: true,
+});
+
+await Ansight.connect(null, {
+  clientName: "My React Native App",
+  expectedAppId: "com.example.app",
+});
+```
+
+`useNativeAllInOneDefaults` defaults to `false`. It only applies the native
+iOS/Android all-in-one defaults: 400 ms sampling, 120 second retention, FPS,
+touch capture, 2000 ms JPEG capture at quality 60 and max width 480, host
+auto-probe, and standard native tools. It is not a master SDK enable switch and
+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.
+
+## Options
+
+The TypeScript `AnsightOptions` surface mirrors Android `AnsightOptions`, iOS
+`AnsightOptions`, and the .NET SDK concepts.
+
+| 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. |
+| `pairingConfigJson` | Legacy top-level pairing JSON. Prefer `hostConnection.*`. |
+| `clientName` | Default client name for host auto-probe and connections. |
+| `sampleFrequencyMilliseconds` | Built-in telemetry sampling interval. |
+| `retentionPeriodSeconds` | Local metric/event retention window. |
+| `enableFramesPerSecond` | Enables native FPS sampling. |
+| `enableBatteryLevel` | Enables battery sampling where available. |
+| `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. |
+| `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. |
+| `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. |
+| `lifecycle` | JS AppState tracking toggle. Defaults to true. |
+
+Example:
+
+```ts
+await Ansight.initializeAndActivate({
+  useNativeAllInOneDefaults: true,
+  toolGuard: "readOnly",
+  sessionJpegCapture: {
+    intervalMilliseconds: 2000,
+    quality: 60,
+    maxWidth: 480,
+  },
+  touchCapture: {
+    captureMoveEvents: true,
+    captureCancelEvents: true,
+    moveCaptureDistanceThreshold: 8,
+    moveCaptureFramesPerSecond: 20,
+  },
+  hostAutoProbe: {
+    enabled: true,
+    clientName: "My React Native App",
+  },
+});
+```
+
+## Native Tool Options
+
+`remoteTools` configures the native tool suites registered by the bridge. Visual tree tools are opt-in:
+
+```ts
+await Ansight.initializeAndActivate(
+  Ansight.createOptionsBuilder()
+    .withReadOnlyToolAccess()
+    .withVisualTreeTools()
+    .withFileSystemTools({
+      additionalRoots: [{ alias: "exports", path: "/tmp/app-exports" }],
+    })
+    .withDatabaseTools({
+      includePlatformRoots: true,
+      additionalRoots: [{ alias: "fixtures", path: "/tmp/app-db" }],
+    })
+    .withPreferencesTools({
+      allowedStores: ["standard"],
+      allowedKeyPrefixes: ["debug."],
+    })
+    .withReflectionTools({
+      includeBuiltInRoots: true,
+      allowedTypePrefixes: ["App."],
+    })
+    .withRemoteTools({
+      secureStorage: {
+        appleService: "com.example.app",
+        preferencesName: "secure_debug",
+        allowedKeys: ["session_token"],
+        allowedKeyPrefixes: ["debug."],
+      },
+    })
+    .build(),
+);
+```
+
+`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`.
+
+## Host Connection
+
+Use `connect(null, options)` for the default automatic flow:
+
+```ts
+await Ansight.connect(null, {
+  clientName: "My React Native App",
+  expectedAppId: "com.example.app",
+});
+```
+
+Automatic connection tries:
+
+1. `hostConnection.bundledDeveloperConfigJson`
+2. native cached host profiles where implemented
+3. saved pairing config
+4. `hostConnection.bundledConfigJson`
+
+Use explicit payloads for QR, paste, or app-owned import flows:
+
+```ts
+await Ansight.connect(pairingJson, {
+  clientName: "My React Native App",
+  expectedAppId: "com.example.app",
+  hostAddressOverride: "192.168.1.20",
+});
+
+await Ansight.savePairingConfig(pairingJson, {
+  expectedAppId: "com.example.app",
+});
+
+await Ansight.clearSavedPairing();
+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.
+
+## Runtime API
+
+The bridge exposes the native SDK runtime surface:
+
+| API | Purpose |
+| --- | --- |
+| `initialize`, `initializeAndActivate`, `activate`, `deactivate`, `clear` | Runtime lifecycle. |
+| `connect`, `disconnect`, `openSession`, `completeSession`, `closeSession` | Host and live-session control. |
+| `savePairingConfig`, `clearSavedPairing`, `clearCachedSession` | Pairing persistence. |
+| `status`, `snapshot`, `hostConnectionStatus`, `currentOptions` | Diagnostics and state. |
+| `registerMetricChannel`, `metric`, `recordMetric` | Metric channels and samples. |
+| `event`, `recordEvent`, `screenViewed`, `trackRoute` | App events and screen views. |
+| `setAppLifecycleState`, `startAppStateTracking`, `stopAppStateTracking` | Lifecycle state capture. |
+| `recordedMetrics`, `recordedEvents` | Local retained telemetry. |
+| `sendClientLog`, `addLogListener` | App-provided live-session log lines and SDK-internal log events. |
+| `captureBuiltInTelemetrySample`, `captureScreenFrame` | Manual sampling and JPEG frame capture. |
+| `isFramesPerSecondEnabled`, `enableFramesPerSecond`, `disableFramesPerSecond` | Runtime FPS sampling status and toggles. |
+| `enableTouchCapture`, `disableTouchCapture` | Runtime touch-capture toggle. |
+| `updateSessionProperties`, `clearSessionProperties` | Grouped session property mutations. |
+| `registerCustomProperty`, `removeCustomProperty`, `clearCustomProperties` | Convenience property mutations. |
+
+Native methods resolve to plain objects. Operation-like methods return
+`{ success, message }`. Host connection methods return a richer result with
+`success`, `message`, `source`, optional `reasonCode`, and optional live-session
+details.
+
+## Telemetry
+
+```ts
+await Ansight.registerMetricChannel({
+  id: 42,
+  name: "Cache",
+  colorHex: "#FF9500",
+  unit: "items",
+  type: "cache",
+});
+
+await Ansight.metric(12, 42);
+await Ansight.event({
+  label: "cache_hit",
+  type: "Info",
+  details: "warm=true",
+  channel: 42,
+});
+
+await Ansight.screenViewed("Orders", { route: "/orders" });
+await Ansight.setAppLifecycleState("foreground");
+```
+
+Read retained samples:
+
+```ts
+const metrics = await Ansight.recordedMetrics(100);
+const events = await Ansight.recordedEvents(100);
+```
+
+## Logs And Session Properties
+
+`sendClientLog` sends an app-provided line over the active live session. It does
+not automatically mirror console logs.
+
+```ts
+await Ansight.sendClientLog("Checkout loaded cartId=debug-42");
+```
+
+`addLogListener` observes SDK-internal logs emitted by the native bridge:
+
+```ts
+const logs = Ansight.addLogListener((entry) => {
+  console.debug(`[Ansight:${entry.level}] ${entry.message}`);
+});
+
+logs.remove();
+```
+
+Session/custom properties are grouped string values:
+
+```ts
+await Ansight.updateSessionProperties({
+  app: {
+    region: "au",
+    tenant: "debug",
+  },
+});
+
+await Ansight.registerCustomProperty("app", "build", "debug");
+await Ansight.removeCustomProperty("app", "tenant");
+await Ansight.clearSessionProperties();
+```
+
+When connected, property mutations are sent immediately. When disconnected, the
+latest values are included in the next `session.open`.
+
+## Tool Guards
+
+| Value | Allowed scopes |
+| --- | --- |
+| `"disabled"` | None |
+| `"readOnly"` | Read |
+| `"readWrite"` | Read, Write |
+| `"fullAccess"` | Read, Write, Delete |
+
+`"full"` is accepted as a compatibility alias for `"fullAccess"`.
+
+## JavaScript Tools
+
+Custom JavaScript tools can be exposed to Ansight Studio:
+
+```ts
+const registration = Ansight.registerTool(
+  {
+    id: "app.state.snapshot",
+    name: "State Snapshot",
+    description: "Returns current app state.",
+    category: "app",
+    scope: "Read",
+    keywords: "state snapshot",
+    argumentsSchema: { type: "object", additionalProperties: true },
+    resultSchema: { type: "object", additionalProperties: true },
+  },
+  async (args, context) => ({
+    success: true,
+    result: {
+      capturedAtUtc: new Date().toISOString(),
+      platform: context.platform,
+      requestId: context.requestId,
+    },
+  }),
+);
+
+await registration.ready;
+await registration.unregister();
+```
+
+The native bridge registers JavaScript tools with `replaceExisting` semantics so
+reloads can refresh handlers.
+
+## React Tools
+
+`installReactTools` registers React Native specific remote tools backed by the
+current React Fiber runtime:
+
+- `react.get_component_tree`
+- `react.get_shadow_tree`
+- `react.find_components`
+- `react.get_component`
+- `react.get_navigation_state`
+- `react.invoke_component_action` when `enableActions` is true
+
+```ts
+const reactTools = Ansight.installReactTools({
+  includeBounds: true,
+  includeProps: false,
+  includeState: false,
+  maxDepth: 60,
+  maxNodes: 5000,
+  navigationRef,
+  enableActions: true,
+  allowedActionProps: ["onPress"],
+});
+
+await reactTools.ready;
+```
+
+The component tree payload redacts sensitive prop and state keys and includes
+native view bounds when React Native exposes a measurable native tag. The shadow
+tree payload flattens composite components and returns the committed React
+Native host/text/root nodes for layout-oriented inspection.
+
+Action invocation is intentionally opt-in. Only function props listed in
+`allowedActionProps` can be invoked, and the tool remains subject to the native
+tool guard.
+
+## React Navigation
+
+Use the tracker to record route changes:
+
+```tsx
+const navigationRef = createNavigationContainerRef();
+const tracker = Ansight.createReactNavigationTracker(navigationRef);
+
+<NavigationContainer
+  ref={navigationRef}
+  onReady={tracker.onReady}
+  onStateChange={tracker.onStateChange}
+>
+  {/* routes */}
+</NavigationContainer>
+```
+
+Pass the same `navigationRef` to `installReactTools` to expose
+`react.get_navigation_state`.
+
+## Error Handlers
+
+`installErrorHandlers` records unhandled JavaScript errors and promise
+rejections as Ansight exception events:
+
+```ts
+const uninstall = Ansight.installErrorHandlers({ chain: true });
+
+// Later, to restore the previous global ErrorUtils handler:
+uninstall();
+```
+
+`chain: false` prevents forwarding to the previous global handler.
+
+## Status And Debugging
+
+```ts
+const status = await Ansight.hostConnectionStatus();
+const snapshot = await Ansight.snapshot();
+const options = await Ansight.currentOptions();
+
+await Ansight.captureBuiltInTelemetrySample();
+await Ansight.captureScreenFrame({ quality: 60, maxWidth: 480 });
+await Ansight.enableTouchCapture();
+await Ansight.disableTouchCapture();
+```
+
+Process memory is sampled by the native runtime. On iOS, `physicalFootprint`
+is the supported process-memory default and reflects the memory footprint used
+by Jetsam, including the React Native runtime inside the app process. On
+Android, `managedHeap`/`javaHeap`, `nativeHeap`, and `residentSetSize`/`rss`
+map to the platform heap and process memory counters.
+
+## Validation
+
+The package checks its JavaScript and TypeScript surfaces:
+
+```sh
+npm run check
+```
+
+The first-party validation app lives in:
+
+```text
+/Users/matthewrobbins/Development/git/ansight-sdk-test-apps/react-native/ansight-react-native-harness
+```
+
+It exercises the native runtime bridge, standard native remote tools,
+JavaScript custom tools, React visual-tree tools, SQLite/file fixtures,
+screenshot capture, and touch/session telemetry.