agent-device 0.12.8 → 0.13.0

package/dist/src/index.d.ts

@@ -414,7 +414,7 @@ export declare class AppError extends Error {
     constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
 }
 
-export declare type AppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'UNKNOWN';
+export declare type AppErrorCode = KnownAppErrorCode | (string & {});
 
 declare type AppErrorDetails = Record<string, unknown> & {
     hint?: string;
@@ -1053,6 +1053,7 @@ export declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
     path?: string;
     overlayRefs?: boolean;
     fullscreen?: boolean;
+    maxSize?: number;
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
 };
 
@@ -1082,6 +1083,8 @@ export declare type CaptureSnapshotResult = {
 
 export declare function centerOfRect(rect: Rect): Point;
 
+declare type ClickButton = 'primary' | 'secondary' | 'middle';
+
 declare type ClickCommandOptions = PressCommandOptions;
 
 export declare type ClickOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
@@ -1645,8 +1648,6 @@ declare type FindBaseOptions = ClientCommandBaseOptions & FindSnapshotCommandOpt
 
 export declare type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
 
-declare type FindLocator_2 = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
-
 export declare type FindOptions = (FindBaseOptions & {
     action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
 }) | (FindBaseOptions & {
@@ -1658,7 +1659,7 @@ export declare type FindOptions = (FindBaseOptions & {
 });
 
 declare type FindReadCommandOptions = CommandContext & {
-    locator?: FindLocator_2;
+    locator?: FindLocator;
     query: string;
     action: Extract<FindAction['kind'], 'exists' | 'wait' | 'get_text' | 'get_attrs'>;
     timeoutMs?: number;
@@ -1796,6 +1797,8 @@ export declare type KeyboardCommandResult = DaemonResponseData & {
     attempts?: number;
 };
 
+declare type KnownAppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'DEVICE_IN_USE' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'AMBIGUOUS_MATCH' | 'UNKNOWN';
+
 declare type Lease = {
     leaseId: string;
     tenantId: string;
@@ -1899,19 +1902,21 @@ declare type MetroBridgeResult = {
     };
 };
 
+declare type MetroBridgeScope = {
+    tenantId: string;
+    runId: string;
+    leaseId: string;
+};
+
 declare type MetroPrepareKind = 'auto' | 'react-native' | 'expo';
 
 export declare type MetroPrepareOptions = {
     projectRoot?: string;
     kind?: MetroPrepareKind;
-    publicBaseUrl: string;
+    publicBaseUrl?: string;
     proxyBaseUrl?: string;
     bearerToken?: string;
-    bridgeScope?: {
-        tenantId: string;
-        runId: string;
-        leaseId: string;
-    };
+    bridgeScope?: MetroBridgeScope;
     launchUrl?: string;
     companionProfileKey?: string;
     companionConsumerKey?: string;
@@ -2030,7 +2035,7 @@ declare type PrepareMetroRuntimeResult = {
 
 declare type PressCommandOptions = CommandContext & {
     target: InteractionTarget_2;
-    button?: 'primary' | 'secondary' | 'middle';
+    button?: ClickButton;
     count?: number;
     intervalMs?: number;
     holdMs?: number;
@@ -2159,11 +2164,13 @@ declare type RepeatedPressOptions = {
 export declare type ReplayRunOptions = AgentDeviceRequestOverrides & {
     path: string;
     update?: boolean;
+    env?: string[];
 };
 
 export declare type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     paths: string[];
     update?: boolean;
+    env?: string[];
     failFast?: boolean;
     timeoutMs?: number;
     retries?: number;
@@ -2244,6 +2251,7 @@ declare type ScreenshotCommandOptions = CommandContext & {
     out?: FileOutputRef;
     fullscreen?: boolean;
     overlayRefs?: boolean;
+    maxSize?: number;
     appId?: string;
     appBundleId?: string;
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
@@ -2446,6 +2454,9 @@ declare type SessionRuntimeHints = {
 export declare type SettingsUpdateOptions = (ClientCommandBaseOptions & {
     setting: 'wifi' | 'airplane' | 'location';
     state: 'on' | 'off';
+}) | (ClientCommandBaseOptions & {
+    setting: 'animations';
+    state: 'on' | 'off';
 }) | (ClientCommandBaseOptions & {
     setting: 'appearance';
     state: 'light' | 'dark' | 'toggle';

package/dist/src/metro.d.ts

@@ -11,11 +11,7 @@ export declare type EnsureMetroTunnelOptions = {
     serverBaseUrl: string;
     bearerToken: string;
     localBaseUrl: string;
-    bridgeScope: {
-        tenantId: string;
-        runId: string;
-        leaseId: string;
-    };
+    bridgeScope: MetroBridgeScope;
     launchUrl?: string;
     profileKey?: string;
     consumerKey?: string;
@@ -79,6 +75,12 @@ export declare type MetroBridgeRuntimePayload = {
     launch_url?: string;
 };
 
+declare type MetroBridgeScope = {
+    tenantId: string;
+    runId: string;
+    leaseId: string;
+};
+
 /** Re-export of {@link SessionRuntimeHints} under the Metro-specific alias used by public API consumers. */
 export declare type MetroRuntimeHints = SessionRuntimeHints;
 
@@ -157,14 +159,10 @@ export declare function prepareRemoteMetro(options: PrepareRemoteMetroOptions):
 export declare type PrepareRemoteMetroOptions = {
     projectRoot: string;
     kind: 'auto' | 'react-native' | 'expo';
-    publicBaseUrl: string;
+    publicBaseUrl?: string;
     proxyBaseUrl?: string;
     proxyBearerToken?: string;
-    bridgeScope?: {
-        tenantId: string;
-        runId: string;
-        leaseId: string;
-    };
+    bridgeScope?: MetroBridgeScope;
     launchUrl?: string;
     profileKey?: string;
     consumerKey?: string;

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "agent-device",
-  "version": "0.12.8",
-  "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
+  "version": "0.13.0",
+  "description": "Agent-driven CLI for mobile UI automation, network inspection, and performance diagnostics across iOS, Android, tvOS, and macOS.",
   "license": "MIT",
   "author": "Callstack",
+  "homepage": "https://agent-device.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/callstackincubator/agent-device.git"
+  },
+  "bugs": {
+    "url": "https://github.com/callstackincubator/agent-device/issues"
+  },
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -120,11 +128,20 @@
     "agent",
     "device",
     "cli",
+    "automation",
     "adb",
     "simctl",
     "devicectl",
     "ios",
-    "android"
+    "android",
+    "tvos",
+    "macos",
+    "react-native",
+    "observability",
+    "diagnostics",
+    "network",
+    "profiling",
+    "performance"
   ],
   "dependencies": {
     "fast-xml-parser": "^5.5.10",

package/skills/agent-device/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info across mobile, TV, and desktop targets.
+description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, or collecting logs, network inspection, and perf snapshots across mobile, TV, and desktop targets.
 ---
 
 # agent-device
@@ -71,3 +71,4 @@ Use this skill as a router with mandatory defaults. Read this file first. For no
 - Need desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
 - Need remote HTTP transport, `connect --remote-config`, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)
   This includes remote React Native runs where `agent-device` now prepares Metro locally and manages the local Metro companion tunnel automatically.
+- Need the React Native component tree, props, state, hooks, or render profiling: use `agent-device react-devtools ...` and the [react-devtools skill](../react-devtools/SKILL.md).

package/skills/agent-device/references/debugging.md

@@ -4,6 +4,8 @@
 
 Open this file when the task turns into failure triage, logs, network inspection, permission prompts, setup trouble, or unstable session behavior.
 
+If the debugging task needs the React Native component tree, props, state, hooks, or render profiling, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow instead of trying to infer those internals from the accessibility tree or app logs alone.
+
 ## Main commands to reach for first
 
 - `logs clear --restart`
@@ -111,7 +113,7 @@ agent-device alert accept
 - `snapshot` returns 0 nodes: the app may no longer be foregrounded or the UI is not stable yet. Re-open the app or retry when state settles.
 - Logs are empty: confirm you opened an app session before `logs clear --restart`.
 - Android logs look stale after relaunch: retry the repro window after the process rebinds.
-- Android accessibility snapshots can lag behind visible screen transitions. The next snapshot now retries briefly after navigation-sensitive actions, but if the tree still looks stale, use `screenshot` as visual truth, wait briefly, then re-run `snapshot -i`.
+- Android accessibility snapshots can lag behind visible screen transitions. The next snapshot retries suspicious trees for a short post-action deadline after navigation-sensitive actions, and `@ref` actions refresh while that window is active. If the tree still looks stale, use `screenshot` as visual truth, wait briefly, then re-run `snapshot -i`. For animation-heavy runs, try `settings animations off` and restore with `settings animations on`.
 - React Native dev warnings or errors keep reappearing: treat them as part of the app state, not as disposable chrome. Capture one clean repro and include them in the summary.
 - Permission prompts block the flow: wait for the alert and handle it explicitly.
 - If snapshots keep returning 0 nodes on an iOS simulator, restart Simulator and re-open the app.

package/skills/agent-device/references/exploration.md

@@ -20,6 +20,7 @@ Open this file when the app or screen is already running and you need to discove
 - User asks what is visible on screen: `snapshot`
 - User asks for exact text from a known target: `get text`
 - User asks you to tap, type, or choose an element: `snapshot -i`, then act
+- User asks for the React Native component tree, props/state/hooks, or render profiling: use `agent-device react-devtools ...` and the `skills/react-devtools` workflow
 - React Native dev or debug build shows warning/error UI: capture enough evidence to identify it, dismiss it if it is not the requested behavior, then continue the flow and report it in the summary
 - The on-screen keyboard is blocking the next step: `keyboard dismiss`; on iOS do this only while an app session is active, and use `keyboard status|get` only on Android
 - UI does not expose the answer: say so plainly; do not browse or force the app into a new state unless asked
@@ -49,8 +50,9 @@ Open this file when the app or screen is already running and you need to discove
 **Android AX tree lag.** After submits, route changes, or composer transitions, the accessibility tree can lag behind the visible UI. If `snapshot -i` and `screenshot` disagree:
 
 1. Trust the screenshot as visual truth.
-2. Take one fresh `snapshot -i`. Android retries briefly after navigation-sensitive actions.
+2. Take one fresh `snapshot -i`. Android retries suspicious trees for a short post-action deadline after navigation-sensitive actions.
 3. If the tree still disagrees with the screenshot, wait briefly, then take one more fresh snapshot. Do not loop snapshots immediately.
+4. For animation-heavy Android runs, use `settings animations off` as an opt-in stabilizer and restore with `settings animations on` after the run.
 
 **React Native dev overlays.** In dev or debug builds, warning or error overlays can block taps, change focus, or hide the real UI. Check for them near app open and after major transitions.
 
@@ -222,7 +224,7 @@ Preferred mapping:
 Notes:
 
 - `wait text` is useful for synchronizing on text presence, but it is not the same as `is visible`.
-- After a nearby navigation or submit on Android, prefer `screenshot`, then `wait 500` or `wait 1000`, then one fresh `snapshot -i` if the accessibility tree seems stale.
+- After a nearby navigation or submit on Android, prefer `screenshot`, then one fresh `snapshot -i`; `@ref` interactions refresh while the Android freshness window is active.
 
 Anti-hallucination rules:
 
@@ -338,6 +340,7 @@ Common batch error categories:
 - `SESSION_NOT_FOUND`: open or select the correct session, then retry.
 - `UNSUPPORTED_OPERATION`: switch to a supported command or surface.
 - `AMBIGUOUS_MATCH`: refine the selector or locator, then retry the failed step.
+- `DEVICE_IN_USE`: the device is held by another session — close or reuse the existing session before retrying.
 - `COMMAND_FAILED`: add sync guards and retry from the failing step.
 
 ## Stop conditions

package/skills/agent-device/references/remote-tenancy.md

@@ -103,8 +103,8 @@ Example `remote-config.json` shape:
   "tenant": "acme",
   "runId": "run-123",
   "sessionIsolation": "tenant",
-  "platform": "android",
-  "metroPublicBaseUrl": "http://127.0.0.1:8081"
+  "platform": "ios",
+  "metroProxyBaseUrl": "https://bridge.example.com"
 }
 ```
 
@@ -112,11 +112,11 @@ Optional overrides stay available for advanced cases:
 
 ```json
 {
-  "session": "adc-android",
-  "leaseBackend": "android-instance",
+  "session": "adc-ios",
+  "leaseBackend": "ios-instance",
   "metroProjectRoot": ".",
   "metroKind": "expo",
-  "metroProxyBaseUrl": "https://bridge.example.com/metro/acme/run-123"
+  "metroPublicBaseUrl": "http://127.0.0.1:8081"
 }
 ```
 
@@ -124,7 +124,10 @@ Optional overrides stay available for advanced cases:
 - Omit Metro fields for non-React Native flows.
 - Put `tenant`, `runId`, and `sessionIsolation` in the remote profile so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags. Add `platform`, `leaseBackend`, `session`, or Metro overrides only when the default inference is not enough for that flow.
 - Explicit command-line flags override connected defaults. Use them intentionally when switching session, platform, target, tenant, run, or lease scope.
-- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally.
+- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally. `metroProxyBaseUrl` is the bridge origin, not a prebuilt `/api/metro/...` route.
+- For cloud stock React Native iOS, use the bridge descriptor's wildcard HTTPS Metro hints directly; do not install or launch the XCTest runner just to make Metro reachable.
+- Android keeps using bridge-provided `/api/metro/runtimes/<runtimeId>/...` Metro routes.
+- `metroPublicBaseUrl` is only needed for direct/non-bridge bundle hints. Bridged profiles can omit it.
 - Use a lease backend that matches the bridge target platform, for example `android-instance`, `ios-instance`, or an explicit `--lease-backend` override.
 
 ## Transport prerequisites

package/skills/agent-device/references/verification.md

@@ -46,7 +46,10 @@ agent-device diff snapshot -i
 
 Use `screenshot` when the proof needs a rendered image instead of a structural tree.
 
+- Add `--max-size 1024` when a full-resolution screenshot is too large for an agent, model, or chat attachment.
 - Add `--overlay-refs` when you want the saved PNG to show fresh `@eN` refs burned into the screenshot.
+- Combine them as `screenshot /tmp/proof.png --max-size 1024 --overlay-refs` when you need a smaller visual proof that still includes tappable refs.
+- Avoid very small `--max-size` values when text, icons, or labels need to remain readable.
 
 ## Visual regression with diff screenshot
 
@@ -126,5 +129,6 @@ agent-device perf --json
 - `startup` is command round-trip timing around `open`.
 - It is not true first-frame or first-interactive telemetry.
 - Android app sessions also expose `memory` (`dumpsys meminfo`) and `cpu` (`dumpsys cpuinfo`) snapshots when the session has an app package context.
-- Apple app sessions on macOS and iOS simulators also expose `memory` and `cpu` process snapshots when the session has an app bundle ID.
-- `fps` is still unavailable, and physical iOS devices still leave `memory` and `cpu` unavailable in this release.
+- Apple app sessions on macOS, iOS simulators, and physical iOS devices also expose `memory` and `cpu` process snapshots when the session has an app bundle ID.
+- On physical iOS devices, sampling uses a short `xcrun xctrace` Activity Monitor capture, so keep the device unlocked, connected, and the app active in the foreground while sampling.
+- `fps` is still unavailable in this release.

package/skills/dogfood/SKILL.md

@@ -166,6 +166,7 @@ agent-device --session {SESSION} close
 - Re-snapshot after any mutation (navigation, modal, list update, form submit).
 - Use `fill` for clear-then-type semantics; use `type` for incremental typing behavior checks.
 - Keep logs optional and targeted: enable/read app logs only when useful for diagnosis.
+- If the issue appears rooted in React Native internals rather than device/app runtime behavior, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow for component-tree or render-profiling inspection.
 - Never read source code of the app under test; findings must come from observed runtime behavior.
 - Write each issue immediately to avoid losing evidence.
 - Never delete screenshots/videos/report artifacts during a session.

package/skills/react-devtools/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: react-devtools
+description: Inspect and profile React Native component trees from agent-device. Use when debugging React Native props, state, hooks, render causes, slow components, excessive re-renders, or questions like why a component re-rendered.
+---
+
+# react-devtools
+
+Use this skill when the task needs React Native internals that are not visible in the accessibility tree: component hierarchy, props, state, hooks, render causes, or profiling data.
+
+Run commands through `agent-device react-devtools`. The command dynamically runs pinned `agent-react-devtools@0.4.0` and passes arguments through 1:1.
+
+The first run may download the pinned package from npm. `agent-device` global flags work before or after `react-devtools`; use `--` before downstream flags only when they intentionally share an `agent-device` global flag name.
+
+## Default flow
+
+1. Use `agent-device` to open the React Native app and verify the visible state when needed.
+2. Check `agent-device react-devtools status`.
+3. If no app is connected, start or wait for the devtools daemon, then reload or relaunch the app.
+4. Inspect with `get tree`, `find`, and `get component`.
+5. Profile only around the interaction being investigated.
+6. Verify the fix with the same command sequence and interaction.
+
+For cross-platform validation with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. Named sessions enable bound-session locks during setup. Restart `agent-device react-devtools` between iOS and Android runs so `status`, `get tree`, and profiling clearly refer to the currently launched app.
+
+## Main commands
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools wait --connected
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools find <ComponentName>
+agent-device react-devtools get component @c5
+agent-device react-devtools profile start
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+## Decision rules
+
+- Need current UI text, refs, screenshots, logs, network, or device metrics: use the `agent-device` skill.
+- Need props, state, hooks, component ownership, render causes, or React profiler data: use this skill.
+- Start component-tree reads with `get tree --depth 3` or `find <name>` to keep output bounded.
+- Labels like `@c5` reset when the app reloads or components remount. After reload, run `wait --connected` and inspect again.
+- Profiling only captures renders between `profile start` and `profile stop`.
+- On Android, set `adb reverse tcp:8097 tcp:8097` for React DevTools. If Metro is local, also set `adb reverse tcp:8081 tcp:8081`.
+
+## References
+
+| File                                    | When to read                                  |
+| --------------------------------------- | --------------------------------------------- |
+| [commands.md](references/commands.md)   | Command reference and common inspection flows |
+| [profiling.md](references/profiling.md) | Render profiling workflow and interpretation  |

package/skills/react-devtools/references/commands.md

@@ -0,0 +1,91 @@
+# React DevTools Commands
+
+All commands are run through `agent-device react-devtools`.
+
+## Connection
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools stop
+agent-device react-devtools status
+agent-device react-devtools wait --connected --timeout 30
+agent-device react-devtools wait --component <ComponentName> --timeout 30
+```
+
+- `status` shows the daemon port, connected apps, component count, profiling state, uptime, and last connection event.
+- Most commands auto-start the daemon, but `start` is useful before launching or reloading the app.
+- React Native development builds connect to the daemon on port 8097. For Android emulators or physical devices, use `adb reverse tcp:8097 tcp:8097` if the app cannot reach the host. If the app also uses local Metro, set `adb reverse tcp:8081 tcp:8081`.
+
+## Validation Notes
+
+- When validating the same app across iOS and Android with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. A named `--session` enables bound-session lock behavior, so setup commands with explicit target selectors can be rejected.
+- Restart the React DevTools daemon between platforms so `status`, `get tree`, and profiling output belong to the currently launched app.
+- Verify the app is visibly loaded with `snapshot` before collecting React internals. Use `react-devtools` for component state and profiling, not for proving the device/app surface is open.
+
+## Component Inspection
+
+```bash
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools get component @c5
+agent-device react-devtools find Button
+agent-device react-devtools find Button --exact
+agent-device react-devtools count
+agent-device react-devtools errors
+```
+
+- `get tree` prints a component hierarchy with labels like `@c1`, `@c2`.
+- Use `--depth` on large apps. Start at `--depth 3` or `--depth 4`.
+- `get component` accepts a label or numeric React fiber id and shows props, state, and hooks.
+- `find` searches by display name. Use `--exact` when fuzzy results are noisy.
+- `errors` lists components with React-tracked warnings or errors.
+
+## Profiling
+
+```bash
+agent-device react-devtools profile start "interaction name"
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile report @c5
+agent-device react-devtools profile timeline --limit 20
+agent-device react-devtools profile commit 3
+agent-device react-devtools profile export profile.json
+agent-device react-devtools profile diff before.json after.json --limit 10
+```
+
+- `profile slow` ranks components by average render duration.
+- `profile rerenders` ranks components by render count.
+- `profile report @cN` shows render causes and changed props/state/hooks for one component.
+- `profile timeline` lists commits. Use `--limit` and `--offset` for long sessions.
+- `profile export` writes React DevTools Profiler JSON that can be diffed later.
+
+## Common Flows
+
+Inspect a component:
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools find SearchScreen
+agent-device react-devtools get component @c12
+```
+
+Profile a slow interaction:
+
+```bash
+agent-device react-devtools profile start "slow search"
+# Trigger the interaction with agent-device or ask the user to perform it.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+Verify a render fix:
+
+```bash
+agent-device react-devtools profile start "after fix"
+# Repeat the same interaction.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```

package/skills/react-devtools/references/profiling.md

@@ -0,0 +1,74 @@
+# React Native Profiling
+
+Use this workflow when the user reports slow interactions, excessive re-renders, unstable props, or unclear render causes.
+
+## Baseline
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools count
+agent-device react-devtools get tree --depth 3
+```
+
+If the app is not connected, run:
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools wait --connected
+```
+
+Then reload or relaunch the React Native app if needed.
+
+## Capture One Interaction
+
+```bash
+agent-device react-devtools profile start "short label"
+# Trigger exactly the interaction being investigated.
+agent-device react-devtools profile stop
+```
+
+Keep the profiling window narrow. Extra navigation, warm-up work, or unrelated gestures make the report harder to interpret.
+
+## Identify Suspects
+
+```bash
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+- A component with high average render time is a slow-render suspect.
+- A component with high render count is a re-render suspect.
+- A component can be both.
+
+## Drill In
+
+```bash
+agent-device react-devtools profile report @c12
+agent-device react-devtools get component @c12
+```
+
+Use `profile report` to identify render causes and changed keys. Use `get component` to inspect current props, state, and hooks.
+
+Common interpretations:
+
+| Signal                                     | Meaning                             | Typical follow-up                              |
+| ------------------------------------------ | ----------------------------------- | ---------------------------------------------- |
+| `props-changed` with function props        | Parent may pass unstable callbacks  | Check whether the parent can use `useCallback` |
+| `props-changed` with object or array props | Parent may pass unstable references | Check whether the parent can use `useMemo`     |
+| `parent-rendered` with many child renders  | Child has no bailout                | Check whether `React.memo` is appropriate      |
+| `state-changed`                            | Component state caused the render   | Check whether the state update is necessary    |
+| `hooks-changed`                            | Hook value or dependency changed    | Inspect hook values and dependencies           |
+
+## Verify
+
+After making a change, repeat the same interaction:
+
+```bash
+agent-device react-devtools profile start "after fix"
+# Repeat the same interaction.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+Compare render counts, average durations, changed keys, and commit counts against the baseline.