refactor: replace wait --components N with wait --component <name>

Wait for a specific component by display name instead of an arbitrary
count. More useful for agents that need to wait for a particular part
of the UI to render after a reload.

Author: piotrski

.changeset/connection-health.md

@@ -2,11 +2,17 @@
 "agent-react-devtools": minor
 ---
 
-Add connection health tracking and `wait` command
+Add `wait` command and connection health tracking
+
+**`wait` command**
+
+Block until a condition is met, with `--timeout` (default 30s) and non-zero exit on timeout:
+
+- `wait --connected` — block until a React app connects via WebSocket
+- `wait --component <name>` — block until a component with the given name appears in the tree
+
+**Connection health in `status`**
 
 - Track connect, disconnect, and reconnect events with timestamps
 - Show last connection event in `status` output (e.g. "app reconnected 3s ago")
 - Show contextual hint when `get tree` returns empty after a disconnect
-- Add `wait --connected` to block until a React app connects
-- Add `wait --components N` to block until N components are mounted
-- Both wait variants support `--timeout` (default 30s) and exit non-zero on timeout

README.md

@@ -125,11 +125,11 @@ Components are labeled `@c1`, `@c2`, etc. You can use these labels or numeric ID
 
 ### Wait
 
-Block until a React app is connected or a component count threshold is met. Useful in scripts or agent workflows where the daemon starts before the app:
+Block until a condition is met. Useful in scripts or agent workflows where the daemon starts before the app:
 
 ```sh
-agent-react-devtools wait --connected [--timeout 30]       # Block until an app connects
-agent-react-devtools wait --components 5 [--timeout 30]    # Block until 5+ components exist
+agent-react-devtools wait --connected [--timeout 30]          # Block until an app connects
+agent-react-devtools wait --component App [--timeout 30]      # Block until a component appears
 ```
 
 Exits with code 0 when the condition is met, or code 1 on timeout.

packages/agent-react-devtools/skills/react-devtools/SKILL.md

@@ -24,7 +24,7 @@ agent-react-devtools start              # Start daemon (auto-starts on first com
 agent-react-devtools stop               # Stop daemon
 agent-react-devtools status             # Check connection, component count, last event
 agent-react-devtools wait --connected   # Block until a React app connects
-agent-react-devtools wait --components 5 # Block until ≥5 components are mounted
+agent-react-devtools wait --component App # Block until a component appears
 ```
 
 ### Component Inspection

packages/agent-react-devtools/skills/react-devtools/references/commands.md

@@ -24,8 +24,8 @@ If profiling is active, shows `Profiling: active`.
 ### `agent-react-devtools wait --connected [--timeout S]`
 Block until at least one React app connects via WebSocket. Resolves immediately if already connected. Default timeout: 30s. Exits non-zero on timeout.
 
-### `agent-react-devtools wait --components N [--timeout S]`
-Block until at least N components are present in the tree. Useful after a reload to wait for the app to fully render. Default timeout: 30s. Exits non-zero on timeout.
+### `agent-react-devtools wait --component <name> [--timeout S]`
+Block until a component with the given display name appears in the tree. Uses case-insensitive substring matching (same as `find`). Useful after a reload to wait for a specific part of the UI to render. Default timeout: 30s. Exits non-zero on timeout.
 
 ## Component Inspection
 

packages/agent-react-devtools/src/cli.ts

@@ -39,7 +39,7 @@ Components:
 
 Wait:
   wait --connected [--timeout S]       Block until an app connects
-  wait --components N [--timeout S]    Block until N components exist
+  wait --component <name> [--timeout S]  Block until a component appears
 
 Profiling:
   profile start [name]          Start profiling session
@@ -221,15 +221,15 @@ async function main(): Promise<void> {
       let ipcCmd: IpcCommand;
       if (flags['connected'] !== undefined) {
         ipcCmd = { type: 'wait', condition: 'connected', timeout: timeoutMs };
-      } else if (flags['components'] !== undefined) {
-        const count = parseInt(flags['components'] as string, 10);
-        if (isNaN(count) || count < 1) {
-          console.error('Usage: devtools wait --components N [--timeout S]');
+      } else if (flags['component'] !== undefined) {
+        const name = flags['component'] as string;
+        if (!name || name === 'true') {
+          console.error('Usage: devtools wait --component <name> [--timeout S]');
           process.exit(1);
         }
-        ipcCmd = { type: 'wait', condition: 'components', count, timeout: timeoutMs };
+        ipcCmd = { type: 'wait', condition: 'component', name, timeout: timeoutMs };
       } else {
-        console.error('Usage: devtools wait --connected|--components N [--timeout S]');
+        console.error('Usage: devtools wait --connected|--component <name> [--timeout S]');
         process.exit(1);
       }
 

packages/agent-react-devtools/src/daemon.ts

@@ -312,8 +312,8 @@ class Daemon {
     switch (cmd.condition) {
       case 'connected':
         return this.bridge.getConnectedAppCount() > 0;
-      case 'components':
-        return this.tree.getComponentCount() >= cmd.count;
+      case 'component':
+        return this.tree.findByName(cmd.name, false).length > 0;
       default:
         return false;
     }

packages/agent-react-devtools/src/types.ts

@@ -117,7 +117,7 @@ export type IpcCommand =
   | { type: 'profile-timeline'; limit?: number }
   | { type: 'profile-commit'; index: number; limit?: number }
   | { type: 'wait'; condition: 'connected'; timeout?: number }
-  | { type: 'wait'; condition: 'components'; count: number; timeout?: number };
+  | { type: 'wait'; condition: 'component'; name: string; timeout?: number };
 
 export interface IpcResponse {
   ok: boolean;

packages/e2e-tests/src/connection-health.test.ts

@@ -164,14 +164,14 @@ describe('Connection health (e2e)', () => {
     expect(data.timeout).toBe(true);
   });
 
-  it('wait --components should resolve when enough components arrive', async () => {
+  it('wait --component should resolve when the named component appears', async () => {
     const ws = await connectMockApp(port);
     await sleep(300);
 
-    // Start waiting for 3 components (root + 2)
+    // Start waiting for Counter to appear
     const waitPromise = sendIpcCommand(
       socketPath,
-      { type: 'wait', condition: 'components', count: 3, timeout: 5000 },
+      { type: 'wait', condition: 'component', name: 'Counter', timeout: 5000 },
       10_000,
     );
 
@@ -188,7 +188,7 @@ describe('Connection health (e2e)', () => {
     expect(resp.ok).toBe(true);
     const data = resp.data as { met: boolean; condition: string };
     expect(data.met).toBe(true);
-    expect(data.condition).toBe('components');
+    expect(data.condition).toBe('component');
 
     ws.close();
     await sleep(300);