rn-devtools-hub

Protocol: events and commands reference

The contract between the app (SDK), the hub and the dashboard. Implementing these types is enough to feed the panels: this is the reference to give an LLM to integrate any app.

Transport

• The app opens a WebSocket to the hub and sends {kind:"hello", role:"device", appName, deviceName, stableId}
• Events are sent in batches: {kind:"events", events: DevtoolsEvent[]}
• DevtoolsEvent = { id: number, type: string, ts: epochMs, payload: object }
• The dashboard sends {kind:"hello", role:"dashboard", token} (token required)
• Dashboard -> app commands: {kind:"command", deviceId, requestId, command, payload} relayed by the hub; the app replies {kind:"commandResult", requestId, result?, error?}

Events (app to dashboard)

Commands (dashboard to app)

Selector notes: by:"role" matches role (precedence) or accessibilityRole, bridging both naming families (img/image, heading/header, searchbox/search, slider/adjustable); name filters on the accessible name (aria-label / accessibilityLabel / alt / placeholder, then rendered text); Text hosts carry an implicit text role; by:"placeholder" matches on substring unless exact, and is the stable way to address a TextInput that carries neither testID nor accessibilityLabel, which is the common case in a form; within is a nested selector restricting the search to a container's subtree.

ui.query and ui.act walk the same tree in the same order, so each match carries the index that addresses it in ui.act for the same selector. Read a position from one, pass it to the other.

ui.act answers for the element it TOUCHED, not only for the one the selector matched:

• target is the match, re-read after the commit for type and clear.
• actedOn appears when the action landed somewhere else: the input inside the container that matched, the Pressable above the view. It carries relation: "descendant" | "ancestor".
• verified is returned for type and clear: exact (the input holds the text), transformed (the app rewrote it: mask, maxLength, trim) or unverifiable (uncontrolled input, or the element left the screen). When the value did not move at all, the answer is ok: false with reason: "value-unchanged" rather than a success.
• result carries what the action measured: scroll offsets, the number of scrollToEnd passes, whether the end was reached.
• index beyond the number of matches is refused with reason: "index-out-of-range" and the candidates. It is never rounded down to the last match.
• committed only says React rendered something, anywhere. It is not a proof that the action reached its target; verified is.

rect is the element's own box when rectFrom is absent. When the element has no measurable instance of its own, the closest measurable neighbour answers and rectFrom states whether it was a descendant or an ancestor, which makes the value an approximation. On the New Architecture a position comes from the shadow tree, and a ScrollView's content offset only reaches it through an asynchronous state update: a measurement taken while a scroll is still settling can lag by a frame.

When count is 0, ui.query adds absence ({reason, exposedBy, present, note}). reason separates the three ways a query returns nothing: attribute-absent (the app sets that prop nowhere, so every query of this family answers zero and retrying is pointless), value-absent (the attribute exists, this value does not, and present samples what does), name-absent (the role exists, the accessible name missed). context.instrumentation plays the same role for the event bus: it is what lets the hub answer "nothing is watching" instead of returning an empty list that reads as "nothing happened".

Navigators keep previous screens MOUNTED (stack cards, inactive tabs). The ui.* commands therefore skip hidden subtrees by default, detected through the signals the navigators set on inactive scenes (importantForAccessibility="no-hide-descendants", accessibilityElementsHidden, RNSScreen activityState: 0, display: none). Pass includeHidden: true to inspect them anyway; hiddenSubtrees tells how many were skipped.

The ui.* commands are served by the SDK (devtools.attachUiAutomation()), which reads the mounted React tree through the React DevTools hook and acts through JS props (onPress, onChangeText). Typing places the exact string given: no autocapitalize interference. This is runtime-level automation (like React Native Testing Library), not native touch injection.

Native adapter (host-side MCP tools)

The hub also exposes OS-level tools that shell out to xcrun simctl and adb on the host machine (validated argv arrays, no shell). They take a target (sim:<udid> or adb:<serial>, from list_targets), which is deliberately distinct from the JS deviceId: the runtime cannot know which simulator it runs on.

session_start restores the Android reverse mappings for both Metro and the Hub before launching. Additional local service ports can be supplied through adbPorts. Native tools and Hubflow captures infer their target when exactly one compatible target is ready, and refuse ambiguous selections.

The device transport exchanges an application-level heartbeat with the Hub. It replaces a half-open socket after a Hub restart, network transition, or return from a suspended native activity. Buffered events are sent after the new connection opens.

Source symbolication uses a short inline budget. If a source remains via: "stack", resolve_source retries against Metro with a longer timeout without repeating or delaying the original UI action.

Event cursor (agents)

The hub stamps every history event with a monotonic per-device seq. The MCP tools get_events_since {cursor} and wait_for_event {type, payloadContains, timeoutMs} use it to follow the stream without polling races: an agent taps, then waits for the matching network.response or screen.ready instead of sleeping.

Hub HTTP endpoints

Rules

• Every payload passed to emit is truncated (~20 KB per string) and sensitive headers must be redacted BEFORE emitting (the SDK does it for its network integrations). emitRaw is reserved for legitimate binary data.
• Unknown events are ignored by the dashboard: you can emit your own types without breaking anything, then contribute a panel.
• The hub history keeps ~3000 events per device; screen.frame events never enter it (broadcast live only).