@ansight/react-native 1.3.0-preview.11 → 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.11`
-- Maven: `ai.ansight:ansight-android:1.3.0-preview.11`
+- 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,
@@ -293,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:
@@ -319,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
 
@@ -339,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. |

package/android/build.gradle

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

package/index.js

@@ -1,7 +1,20 @@
 "use strict";
 
+const { ensureReactInspectionHook } = require("./react-inspection-hook");
+const { createReactCoordinateSpace } = require("./react-tree-geometry");
+const { reactSemanticRole, reactSupportedActions } = require("./react-tree-semantics");
+
+// Production React Native renderers only look for the DevTools hook once, when
+// the renderer module initializes. Install a minimal root tracker while this
+// package is loading so Fabric and Paper can report their roots before the app's
+// first render. Development runtimes keep their full React DevTools hook.
+if (typeof __DEV__ === "undefined" || !__DEV__) {
+  ensureReactInspectionHook(typeof global !== "undefined" ? global : undefined);
+}
+
 const {
   AppState,
+  Dimensions,
   NativeEventEmitter,
   NativeModules,
   Platform,
@@ -1531,36 +1544,16 @@ function summarizeProps(props) {
   return summary;
 }
 
-function reactSemanticRole(type, props, fiberTag) {
-  const declared = props && (props.accessibilityRole || props.role);
-  if (declared) return String(declared).toLowerCase();
-  if (fiberTag === 6 || /text/i.test(type)) return "text";
-  if (/button|pressable|touchable/i.test(type)) return "button";
-  if (/textinput/i.test(type)) return "textbox";
-  if (/switch/i.test(type)) return "switch";
-  if (/scrollview|flatlist|sectionlist/i.test(type)) return "scrollview";
-  return "view";
-}
-
-function reactSupportedActions(type, props) {
-  const actions = [];
-  if (props && typeof props.onPress === "function") actions.push("tap");
-  if (props && (typeof props.onChangeText === "function" || /textinput/i.test(type))) {
-    actions.push("typeText", "focus");
-  }
-  if (/scrollview|flatlist|sectionlist/i.test(type) || (props && typeof props.onScroll === "function")) {
-    actions.push("scroll", "swipe");
-  }
-  return actions;
-}
-
 function applyReactTargetability(node, fiber, props, type) {
   const style = StyleSheet && typeof StyleSheet.flatten === "function"
     ? StyleSheet.flatten(props && props.style)
     : props && props.style;
   node.text = node.label || (node.visual && node.visual.text) || null;
-  node.role = reactSemanticRole(type, props, fiber.tag);
   node.supportedActions = reactSupportedActions(type, props);
+  node.role = reactSemanticRole(type, props, fiber.tag);
+  if (node.role === "view" && node.supportedActions.includes("tap")) {
+    node.role = "button";
+  }
   node.visible = !(style && style.display === "none") && !(props && props.accessibilityElementsHidden);
   node.enabled = !(props && (props.disabled === true || props.accessibilityState && props.accessibilityState.disabled === true));
   node.focusable = !!(props && props.focusable) || node.supportedActions.includes("focus");
@@ -1914,6 +1907,7 @@ async function captureReactVisualTree(rawOptions = {}) {
     source: "react",
     adapter: "react.fiber",
     treeKind: "component",
+    coordinateSpace: createReactCoordinateSpace(Dimensions, context.nodesWithNativeTags),
     capturedAtUtc: new Date().toISOString(),
     hookAvailable: roots.hookAvailable,
     renderers: roots.renderers,
@@ -1974,6 +1968,7 @@ async function captureReactShadowTree(rawOptions = {}) {
     source: "react-native",
     adapter: "react-native.host-fiber",
     treeKind: "shadow",
+    coordinateSpace: createReactCoordinateSpace(Dimensions, context.nodesWithNativeTags),
     capturedAtUtc: new Date().toISOString(),
     hookAvailable: roots.hookAvailable,
     renderers: roots.renderers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansight/react-native",
-  "version": "1.3.0-preview.11",
+  "version": "1.3.0-preview.12",
   "description": "React Native bridge for the Ansight mobile SDK.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,6 +25,9 @@
     "README.md",
     "index.js",
     "index.d.ts",
+    "react-inspection-hook.js",
+    "react-tree-geometry.js",
+    "react-tree-semantics.js",
     "network.js",
     "session-properties.js",
     "app.plugin.js",

package/react-inspection-hook.js

@@ -0,0 +1,76 @@
+"use strict";
+
+const ANSIGHT_HOOK_MARKER = "__ansightReactInspectionHook";
+
+function hasElementState(current) {
+  const state = current && current.memoizedState;
+  if (!state || typeof state !== "object") {
+    return true;
+  }
+  if (!Object.prototype.hasOwnProperty.call(state, "element")) {
+    return true;
+  }
+  return state.element != null;
+}
+
+function createReactInspectionHook() {
+  const renderers = new Map();
+  const fiberRoots = new Map();
+  let nextRendererId = 1;
+
+  function rootsForRenderer(rendererId) {
+    let roots = fiberRoots.get(rendererId);
+    if (!roots) {
+      roots = new Set();
+      fiberRoots.set(rendererId, roots);
+    }
+    return roots;
+  }
+
+  return {
+    [ANSIGHT_HOOK_MARKER]: true,
+    supportsFiber: true,
+    isDisabled: false,
+    renderers,
+    _fiberRoots: fiberRoots,
+    inject(renderer) {
+      const rendererId = nextRendererId++;
+      renderers.set(rendererId, renderer);
+      rootsForRenderer(rendererId);
+      return rendererId;
+    },
+    getFiberRoots(rendererId) {
+      return rootsForRenderer(rendererId);
+    },
+    onCommitFiberRoot(rendererId, root) {
+      const roots = rootsForRenderer(rendererId);
+      if (root && root.current && hasElementState(root.current)) {
+        roots.add(root);
+      } else {
+        roots.delete(root);
+      }
+    },
+    onCommitFiberUnmount() {},
+  };
+}
+
+function ensureReactInspectionHook(runtimeGlobal) {
+  if (!runtimeGlobal || typeof runtimeGlobal !== "object") {
+    return undefined;
+  }
+
+  const existing = runtimeGlobal.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (existing) {
+    return existing;
+  }
+
+  const hook = createReactInspectionHook();
+  runtimeGlobal.__REACT_DEVTOOLS_GLOBAL_HOOK__ = hook;
+  return hook;
+}
+
+module.exports = {
+  ANSIGHT_HOOK_MARKER,
+  createReactInspectionHook,
+  ensureReactInspectionHook,
+};

package/react-tree-geometry.js

@@ -0,0 +1,61 @@
+"use strict";
+
+function readDimensionSize(dimensions, name) {
+  if (!dimensions || typeof dimensions.get !== "function") {
+    return null;
+  }
+  try {
+    const value = dimensions.get(name);
+    const width = Number(value && value.width);
+    const height = Number(value && value.height);
+    if (Number.isFinite(width) && width > 0 && Number.isFinite(height) && height > 0) {
+      return { width, height };
+    }
+  } catch (_) {
+    // Some non-native React renderers do not expose screen dimensions.
+  }
+  return null;
+}
+
+function viewportHostBounds(nodes, screenSize) {
+  const candidates = (nodes || [])
+    .map((node) => node && node.bounds)
+    .filter((bounds) => bounds
+      && Number.isFinite(Number(bounds.x))
+      && Number.isFinite(Number(bounds.y))
+      && Number.isFinite(Number(bounds.width))
+      && Number.isFinite(Number(bounds.height))
+      && Number(bounds.width) >= screenSize.width * 0.85
+      && Number(bounds.height) >= screenSize.height * 0.5);
+  if (candidates.length === 0) {
+    return null;
+  }
+  return candidates.reduce((largest, candidate) => (
+    Number(candidate.width) * Number(candidate.height)
+      > Number(largest.width) * Number(largest.height)
+      ? candidate
+      : largest
+  ));
+}
+
+function createReactCoordinateSpace(dimensions, measuredNodes = []) {
+  const screenSize = readDimensionSize(dimensions, "screen");
+  const windowSize = readDimensionSize(dimensions, "window");
+  const size = screenSize || windowSize;
+  if (!size) {
+    return undefined;
+  }
+
+  const hostBounds = viewportHostBounds(measuredNodes, size);
+  return {
+    x: hostBounds ? Math.min(0, Number(hostBounds.x)) : 0,
+    y: hostBounds ? Math.min(0, Number(hostBounds.y)) : 0,
+    width: size.width,
+    height: size.height,
+    source: screenSize ? "react-native.screen" : "react-native.window",
+  };
+}
+
+module.exports = {
+  createReactCoordinateSpace,
+};

package/react-tree-semantics.js

@@ -0,0 +1,33 @@
+"use strict";
+
+function reactSemanticRole(type, props, fiberTag) {
+  const declared = props && (props.accessibilityRole || props.role);
+  if (declared) return String(declared).toLowerCase();
+  if (fiberTag === 6 || /text/i.test(type)) return "text";
+  if (/button|pressable|touchable/i.test(type)) return "button";
+  if (/textinput/i.test(type)) return "textbox";
+  if (/switch/i.test(type)) return "switch";
+  if (/scrollview|flatlist|sectionlist/i.test(type)) return "scrollview";
+  return "view";
+}
+
+function reactSupportedActions(type, props) {
+  const actions = [];
+  if (props && (
+    typeof props.onPress === "function"
+    || typeof props.onClick === "function"
+    || typeof props.onResponderRelease === "function"
+  )) actions.push("tap");
+  if (props && (typeof props.onChangeText === "function" || /textinput/i.test(type))) {
+    actions.push("typeText", "focus");
+  }
+  if (/scrollview|flatlist|sectionlist/i.test(type) || (props && typeof props.onScroll === "function")) {
+    actions.push("scroll", "swipe");
+  }
+  return actions;
+}
+
+module.exports = {
+  reactSemanticRole,
+  reactSupportedActions,
+};