feat: add React component labels for agents

.changeset/label-based-react-node-lookups.md

@@ -0,0 +1,6 @@
+---
+'@rozenite/middleware': patch
+'rozenite': patch
+---
+
+Add stable React component labels so nodes can be looked up by labels like `@c2` across the React agent tools.

packages/cli/src/commands/agent/runtime/react/__tests__/store.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest';
+import { createReactTreeStore } from '../store.js';
+
+const DEVICE_ID = 'device-1';
+
+const waitFor = async (predicate: () => boolean): Promise<void> => {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    if (predicate()) {
+      return;
+    }
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+  }
+
+  expect(predicate()).toBe(true);
+};
+
+const createStoreWithBridgeStub = (
+  sent: Array<{ event: string; payload: unknown }>,
+) => {
+  return createReactTreeStore({
+    createBridge: async (options) => ({
+      ingest: () => null,
+      send: (event, payload) => {
+        sent.push({ event, payload });
+        options?.sendMessage?.({ event, payload });
+      },
+      startProfiling: () => undefined,
+      stopProfiling: () => undefined,
+      reloadAndProfile: () => undefined,
+      getProfilingStatus: () => ({
+        supportsProfiling: true,
+        supportsReloadAndProfile: false,
+        isProfilingStarted: false,
+        isProcessingData: false,
+        hasProfilingData: false,
+        rootsWithData: 0,
+        rootsCount: 0,
+      }),
+      getProfilingDataSnapshot: () => null,
+      getCommitData: () => {
+        throw new Error('No commit data');
+      },
+    }),
+  });
+};
+
+const createStoreWithTree = () => {
+  const store = createReactTreeStore();
+  store.registerDevice(DEVICE_ID);
+  store.syncTree(DEVICE_ID, {
+    roots: [1],
+    nodes: [
+      {
+        nodeId: 1,
+        displayName: 'Root',
+        elementType: 'root',
+        childIds: [2, 3],
+      },
+      {
+        nodeId: 2,
+        displayName: 'App',
+        elementType: 'function',
+        parentId: 1,
+        childIds: [4],
+      },
+      {
+        nodeId: 3,
+        displayName: 'Sidebar',
+        elementType: 'function',
+        parentId: 1,
+        childIds: [],
+      },
+      {
+        nodeId: 4,
+        displayName: 'Button',
+        elementType: 'host',
+        parentId: 2,
+        childIds: [],
+      },
+    ],
+  });
+
+  return store;
+};
+
+describe('CLI React tree store labels', () => {
+  it('resolves labels for node lookup while keeping numeric nodeId lookup working', () => {
+    const store = createStoreWithTree();
+
+    expect(store.getNode(DEVICE_ID, { id: '@c2' })).toMatchObject({
+      nodeId: 2,
+      label: '@c2',
+      displayName: 'App',
+      parentLabel: '@c1',
+    });
+    expect(store.getNode(DEVICE_ID, { nodeId: 2 })).toMatchObject({
+      nodeId: 2,
+      label: '@c2',
+      displayName: 'App',
+    });
+  });
+
+  it('resolves labels for children and inspectable requests', async () => {
+    const sent: Array<{ event: string; payload: unknown }> = [];
+    const store = createStoreWithBridgeStub(sent);
+    store.registerDevice(DEVICE_ID, {
+      sendMessage: () => undefined,
+    });
+    store.syncTree(DEVICE_ID, {
+      roots: [1],
+      nodes: [
+        {
+          nodeId: 1,
+          displayName: 'Root',
+          elementType: 'root',
+          childIds: [2],
+        },
+        {
+          nodeId: 2,
+          displayName: 'App',
+          elementType: 'function',
+          parentId: 1,
+          rendererId: 7,
+          childIds: [],
+        },
+      ],
+    });
+
+    expect(store.getChildren(DEVICE_ID, { id: '@c1', limit: 3 }).items).toEqual([
+      expect.objectContaining({
+        nodeId: 2,
+        label: '@c2',
+        parentLabel: '@c1',
+      }),
+    ]);
+
+    const propsPromise = store.getProps(DEVICE_ID, { id: '@c2' });
+    await waitFor(() => sent.length > 0);
+
+    expect(sent.at(-1)).toEqual({
+      event: 'inspectElement',
+      payload: {
+        forceFullData: true,
+        id: 2,
+        path: null,
+        rendererID: 7,
+        requestID: 1,
+      },
+    });
+
+    await store.ingestReactDevToolsMessage(DEVICE_ID, {
+      event: 'inspectedElement',
+      payload: {
+        id: 2,
+        type: 'full-data',
+        value: {
+          props: { title: 'Hello' },
+        },
+      },
+    });
+
+    await expect(propsPromise).resolves.toMatchObject({
+      items: [{ name: 'title', value: 'Hello' }],
+    });
+  });
+});

packages/cli/src/commands/agent/runtime/react/store.ts

@@ -65,6 +65,8 @@ type ReactChangeDescription = {
 type DeviceReactTreeState = {
   rootIds: number[];
   nodesById: Map<number, ReactNodeRecord>;
+  labelByNodeId: Map<number, string>;
+  nodeIdByLabel: Map<string, number>;
   inspectedById: Map<number, ReactInspectedNodeRecord>;
   bridge: ReactDevToolsBridge | null;
   bridgePromise: Promise<ReactDevToolsBridge> | null;
@@ -180,6 +182,7 @@ const delay = async (ms: number): Promise<void> => {
 const ensureNodeSummary = (node: ReactNodeRecord): ReactNodeSummary => {
   return {
     nodeId: node.nodeId,
+    label: '@c?',
     displayName: node.displayName,
     elementType: node.elementType,
     ...(node.key !== undefined ? { key: node.key } : {}),
@@ -188,12 +191,48 @@ const ensureNodeSummary = (node: ReactNodeRecord): ReactNodeSummary => {
   };
 };
 
-const getNodeId = (value: unknown): number => {
-  if (!Number.isInteger(value)) {
-    throw new Error('"nodeId" must be an integer');
+const ensureNodeSummaryForState = (
+  state: DeviceReactTreeState,
+  node: ReactNodeRecord,
+): ReactNodeSummary => {
+  const parentLabel = node.parentId !== undefined
+    ? state.labelByNodeId.get(node.parentId)
+    : undefined;
+
+  return {
+    ...ensureNodeSummary(node),
+    label: state.labelByNodeId.get(node.nodeId) ?? '@c?',
+    ...(parentLabel !== undefined ? { parentLabel } : {}),
+  };
+};
+
+const resolveNodeId = (
+  state: DeviceReactTreeState,
+  value: unknown,
+  fieldName: string,
+): number => {
+  if (Number.isInteger(value)) {
+    return Number(value);
   }
 
-  return Number(value);
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (/^@c\d+$/.test(trimmed)) {
+      const nodeId = state.nodeIdByLabel.get(trimmed);
+      if (nodeId === undefined) {
+        throw new Error(`Component label "${trimmed}" no longer exists in the current React tree.`);
+      }
+
+      return nodeId;
+    }
+
+    const parsed = Number(trimmed);
+    if (Number.isInteger(parsed)) {
+      return parsed;
+    }
+  }
+
+  throw new Error(`"${fieldName}" must be an integer or component label like "@c12"`);
 };
 
 const ensureNodeExists = (state: DeviceReactTreeState, nodeId: number): ReactNodeRecord => {
@@ -205,6 +244,29 @@ const ensureNodeExists = (state: DeviceReactTreeState, nodeId: number): ReactNod
   return node;
 };
 
+const getRequestedNodeId = (
+  state: DeviceReactTreeState,
+  request: Record<string, unknown>,
+): number => {
+  return resolveNodeId(
+    state,
+    request.id !== undefined ? request.id : request.nodeId,
+    request.id !== undefined ? 'id' : 'nodeId',
+  );
+};
+
+const getOptionalNodeId = (
+  state: DeviceReactTreeState,
+  value: unknown,
+  fieldName: string,
+): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return resolveNodeId(state, value, fieldName);
+};
+
 const createSerializableSnapshot = (
   value: unknown,
   depth = 3,
@@ -439,6 +501,38 @@ const toReactNodeRecord = (node: ReactTreeNodeInput): ReactNodeRecord => {
   };
 };
 
+const rebuildLabels = (state: DeviceReactTreeState): void => {
+  state.labelByNodeId.clear();
+  state.nodeIdByLabel.clear();
+
+  const visited = new Set<number>();
+  let nextLabelIndex = 1;
+
+  const walk = (nodeId: number): void => {
+    if (visited.has(nodeId) || !state.nodesById.has(nodeId)) {
+      return;
+    }
+
+    visited.add(nodeId);
+    const label = `@c${nextLabelIndex++}`;
+    state.labelByNodeId.set(nodeId, label);
+    state.nodeIdByLabel.set(label, nodeId);
+
+    const node = state.nodesById.get(nodeId);
+    if (!node) {
+      return;
+    }
+
+    for (const childId of node.childIds) {
+      walk(childId);
+    }
+  };
+
+  for (const rootId of state.rootIds) {
+    walk(rootId);
+  }
+};
+
 export const createReactTreeStore = (
   options?: {
     createBridge?: (options?: {
@@ -458,6 +552,8 @@ export const createReactTreeStore = (
     const created: DeviceReactTreeState = {
       rootIds: [],
       nodesById: new Map(),
+      labelByNodeId: new Map(),
+      nodeIdByLabel: new Map(),
       inspectedById: new Map(),
       bridge: null,
       bridgePromise: null,
@@ -511,6 +607,7 @@ export const createReactTreeStore = (
 
     state.rootIds = rootIds.filter((rootId) => nodesById.has(rootId));
     state.nodesById = nodesById;
+    rebuildLabels(state);
     // Tree-sync snapshots replace current topology; invalidate stale inspected snapshots.
     state.inspectedById.clear();
   };
@@ -794,7 +891,7 @@ export const createReactTreeStore = (
     }
     const query = rawQuery.trim().toLowerCase();
 
-    const rootId = Number.isInteger(request.rootId) ? Number(request.rootId) : undefined;
+    const rootId = getOptionalNodeId(state, request.rootId, 'rootId');
     const match = normalizeMatch(request.match);
     const limit = normalizeLimit(request.limit);
 
@@ -833,7 +930,9 @@ export const createReactTreeStore = (
 
     const safeOffset = Math.max(0, Math.min(offset, matched.length));
     const end = Math.min(safeOffset + limit, matched.length);
-    const items = matched.slice(safeOffset, end).map(ensureNodeSummary);
+    const items = matched
+      .slice(safeOffset, end)
+      .map((node) => ensureNodeSummaryForState(state, node));
     const hasMore = end < matched.length;
     const nextCursor = hasMore
       ? encodeCursor({
@@ -858,15 +957,15 @@ export const createReactTreeStore = (
   const getNode = (deviceId: string, rawRequest: unknown): ReactNodeSummary => {
     const request = getRecord(rawRequest) || {};
     const state = getOrCreateState(deviceId);
-    const nodeId = getNodeId(request.nodeId);
+    const nodeId = getRequestedNodeId(state, request);
     const node = ensureNodeExists(state, nodeId);
-    return ensureNodeSummary(node);
+    return ensureNodeSummaryForState(state, node);
   };
 
   const getChildren = (deviceId: string, rawRequest: unknown): ReactGetChildrenResult => {
     const request = getRecord(rawRequest) || {};
     const state = getOrCreateState(deviceId);
-    const nodeId = getNodeId(request.nodeId);
+    const nodeId = getRequestedNodeId(state, request);
     const node = ensureNodeExists(state, nodeId);
     const limit = normalizeLimit(request.limit);
     const filtersHash = hashFilters({ nodeId });
@@ -889,7 +988,9 @@ export const createReactTreeStore = (
       .filter((child): child is ReactNodeRecord => Boolean(child));
     const safeOffset = Math.max(0, Math.min(offset, children.length));
     const end = Math.min(safeOffset + limit, children.length);
-    const items = children.slice(safeOffset, end).map(ensureNodeSummary);
+    const items = children
+      .slice(safeOffset, end)
+      .map((child) => ensureNodeSummaryForState(state, child));
     const hasMore = end < children.length;
     const nextCursor = hasMore
       ? encodeCursor({
@@ -968,7 +1069,7 @@ export const createReactTreeStore = (
   ): Promise<ReactGetInspectableResult> => {
     const request = getRecord(rawRequest) || {};
     const state = getOrCreateState(deviceId);
-    const nodeId = getNodeId(request.nodeId);
+    const nodeId = getRequestedNodeId(state, request);
     ensureNodeExists(state, nodeId);
     const path = kind === 'hooks' ? normalizePath(request.path) : [];