@react-grab/cli 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/cli.cjs

@@ -2707,7 +2707,7 @@ var previewPackageJsonAgentRemoval = (projectRoot, agent) => {
 };
 
 // src/commands/add.ts
-var VERSION = "0.1.0-beta.2";
+var VERSION = "0.1.0-beta.3";
 var add = new commander.Command().name("add").alias("install").description("add an agent integration or MCP server").argument(
   "[agent]",
   `agent to add (${AGENTS.join(", ")}, mcp, skill)`
@@ -3236,6 +3236,15 @@ var add = new commander.Command().name("add").alias("install").description("add
     handleError(error48);
   }
 });
+
+// src/utils/constants.ts
+var MAX_SUGGESTIONS_COUNT = 30;
+var MAX_KEY_HOLD_DURATION_MS = 2e3;
+var MAX_CONTEXT_LINES = 50;
+var COMPONENT_STACK_MAX_DEPTH = 10;
+
+// src/utils/browser-automation.ts
+var LOAD_STATES = /* @__PURE__ */ new Set(["load", "domcontentloaded", "networkidle"]);
 var ensureHealthyServer = async (options2 = {}) => {
   const cliPath = process.argv[1];
   const serverRunning = await browser$1.isServerRunning();
@@ -3266,16 +3275,65 @@ var getOrCreatePage = async (serverUrl, name) => {
   }
   return response.json();
 };
+var getReactContextForActiveElement = async (page) => {
+  try {
+    return page.evaluate(async (maxDepth) => {
+      const activeElement = document.activeElement;
+      if (!activeElement || activeElement === document.body) return null;
+      const reactGrab = globalThis.__REACT_GRAB__;
+      if (!reactGrab?.getSource) return null;
+      const source = await reactGrab.getSource(activeElement);
+      if (!source) return null;
+      const componentStack = [];
+      if (source.componentName) {
+        componentStack.push(source.componentName);
+      }
+      const fiberKey = Object.keys(activeElement).find(
+        (key) => key.startsWith("__reactFiber$") || key.startsWith("__reactInternalInstance$")
+      );
+      if (fiberKey) {
+        let fiber = activeElement[fiberKey];
+        let depth = 0;
+        while (fiber?.return && depth < maxDepth) {
+          fiber = fiber.return;
+          if (fiber.tag === 0 || fiber.tag === 1 || fiber.tag === 11) {
+            const name = typeof fiber.type === "object" ? fiber.type?.displayName || fiber.type?.name : null;
+            if (name && !name.startsWith("_") && !componentStack.includes(name)) {
+              componentStack.push(name);
+            }
+          }
+          depth++;
+        }
+      }
+      return {
+        element: activeElement.tagName.toLowerCase(),
+        component: source.componentName || void 0,
+        source: source.filePath ? `${source.filePath}${source.lineNumber ? `:${source.lineNumber}` : ""}` : void 0,
+        componentStack: componentStack.length > 0 ? componentStack : void 0
+      };
+    }, COMPONENT_STACK_MAX_DEPTH);
+  } catch {
+    return null;
+  }
+};
 var createOutputJson = (getPage, pageName) => {
   return async (ok, result, error48) => {
     const page = getPage();
+    let reactContext;
+    if (page && ok) {
+      const context = await getReactContextForActiveElement(page);
+      if (context) {
+        reactContext = context;
+      }
+    }
     return {
       ok,
       url: page?.url() ?? "",
       title: page ? await page.title().catch(() => "") : "",
       page: pageName,
       ...result !== void 0 && { result },
-      ...error48 && { error: error48 }
+      ...error48 && { error: error48 },
+      ...reactContext && { reactContext }
     };
   };
 };
@@ -3334,6 +3392,24 @@ var createRefHelper = (getActivePage2) => {
       return g2.__REACT_GRAB__.getSource(el);
     }, element);
   };
+  const getProps = async (refId) => {
+    const element = await getElement(refId);
+    const currentPage2 = getActivePage2();
+    return currentPage2.evaluate((el) => {
+      const g2 = globalThis;
+      if (!g2.__REACT_GRAB_GET_PROPS__) return null;
+      return g2.__REACT_GRAB_GET_PROPS__(el);
+    }, element);
+  };
+  const getState = async (refId) => {
+    const element = await getElement(refId);
+    const currentPage2 = getActivePage2();
+    return currentPage2.evaluate((el) => {
+      const g2 = globalThis;
+      if (!g2.__REACT_GRAB_GET_STATE__) return null;
+      return g2.__REACT_GRAB_GET_STATE__(el);
+    }, element);
+  };
   return (refId) => {
     return new Proxy(
       {},
@@ -3345,6 +3421,12 @@ var createRefHelper = (getActivePage2) => {
           if (prop === "source") {
             return () => getSource(refId);
           }
+          if (prop === "props") {
+            return () => getProps(refId);
+          }
+          if (prop === "state") {
+            return () => getState(refId);
+          }
           if (prop === "screenshot") {
             return (options2) => getElement(refId).then(
               (el) => el.screenshot({ scale: "css", ...options2 })
@@ -3358,6 +3440,50 @@ var createRefHelper = (getActivePage2) => {
     );
   };
 };
+var createComponentHelper = (getActivePage2) => {
+  return async (componentName, options2) => {
+    const currentPage2 = getActivePage2();
+    const nth = options2?.nth;
+    const elementHandles = await currentPage2.evaluateHandle(
+      async (args) => {
+        const g2 = globalThis;
+        if (!g2.__REACT_GRAB_FIND_BY_COMPONENT__) {
+          throw new Error("React introspection not available. Make sure react-grab is installed.");
+        }
+        const result = await g2.__REACT_GRAB_FIND_BY_COMPONENT__(args.name, args.nth !== void 0 ? { nth: args.nth } : void 0);
+        if (!result) return null;
+        if (args.nth !== void 0) {
+          const single = result;
+          return single?.element || null;
+        }
+        const arr = result;
+        return arr.map((m2) => m2.element);
+      },
+      { name: componentName, nth }
+    );
+    const value = await elementHandles.jsonValue().catch(() => null);
+    if (value === null) {
+      await elementHandles.dispose();
+      return null;
+    }
+    if (nth !== void 0) {
+      const element = elementHandles.asElement();
+      if (!element) {
+        await elementHandles.dispose();
+        return null;
+      }
+      return element;
+    }
+    const jsHandles = await elementHandles.getProperties();
+    const handles = [];
+    for (const [, handle] of jsHandles) {
+      const element = handle.asElement();
+      if (element) handles.push(element);
+    }
+    await elementHandles.dispose();
+    return handles;
+  };
+};
 var createFillHelper = (ref, getActivePage2) => {
   return async (refId, text) => {
     const element = await ref(refId);
@@ -3459,35 +3585,22 @@ var createDispatchHelper = (getActivePage2) => {
   };
 };
 var createGrabHelper = (ref, getActivePage2) => {
+  const evaluateGrabMethod = async (methodName, defaultValue) => {
+    const currentPage2 = getActivePage2();
+    return currentPage2.evaluate(
+      ({ method, fallback }) => {
+        const grab = globalThis.__REACT_GRAB__;
+        return grab?.[method]?.() ?? fallback;
+      },
+      { method: methodName, fallback: defaultValue }
+    );
+  };
   return {
-    activate: async () => {
-      const currentPage2 = getActivePage2();
-      await currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        g2.__REACT_GRAB__?.activate();
-      });
-    },
-    deactivate: async () => {
-      const currentPage2 = getActivePage2();
-      await currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        g2.__REACT_GRAB__?.deactivate();
-      });
-    },
-    toggle: async () => {
-      const currentPage2 = getActivePage2();
-      await currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        g2.__REACT_GRAB__?.toggle();
-      });
-    },
-    isActive: async () => {
-      const currentPage2 = getActivePage2();
-      return currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        return g2.__REACT_GRAB__?.isActive() ?? false;
-      });
-    },
+    activate: () => evaluateGrabMethod("activate", void 0),
+    deactivate: () => evaluateGrabMethod("deactivate", void 0),
+    toggle: () => evaluateGrabMethod("toggle", void 0),
+    isActive: () => evaluateGrabMethod("isActive", false),
+    getState: () => evaluateGrabMethod("getState", null),
     copyElement: async (refId) => {
       const element = await ref(refId);
       if (!element) return false;
@@ -3496,13 +3609,6 @@ var createGrabHelper = (ref, getActivePage2) => {
         const g2 = globalThis;
         return g2.__REACT_GRAB__?.copyElement([el]) ?? false;
       }, element);
-    },
-    getState: async () => {
-      const currentPage2 = getActivePage2();
-      return currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        return g2.__REACT_GRAB__?.getState() ?? null;
-      });
     }
   };
 };
@@ -3518,7 +3624,7 @@ var createWaitForHelper = (getActivePage2) => {
   return async (selectorOrState, options2) => {
     const currentPage2 = getActivePage2();
     const timeout = options2?.timeout;
-    if (selectorOrState === "load" || selectorOrState === "domcontentloaded" || selectorOrState === "networkidle") {
+    if (LOAD_STATES.has(selectorOrState)) {
       await currentPage2.waitForLoadState(selectorOrState, { timeout });
       return;
     }
@@ -3529,6 +3635,33 @@ var createWaitForHelper = (getActivePage2) => {
     await currentPage2.waitForSelector(selectorOrState, { timeout });
   };
 };
+var connectToBrowserPage = async (pageName) => {
+  const { chromium: chromium2 } = await import('playwright-core');
+  const { findPageByTargetId: findPageByTargetId2 } = await import('@react-grab/browser');
+  const { serverUrl } = await ensureHealthyServer();
+  const pageInfo = await getOrCreatePage(serverUrl, pageName);
+  const browser2 = await chromium2.connectOverCDP(pageInfo.wsEndpoint);
+  const page = await findPageByTargetId2(browser2, pageInfo.targetId);
+  if (!page) {
+    await browser2.close();
+    throw new Error(`Page "${pageName}" not found`);
+  }
+  return { browser: browser2, page, serverUrl };
+};
+var createMcpErrorResponse = (error48) => {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          ok: false,
+          error: error48 instanceof Error ? error48.message : "Failed"
+        })
+      }
+    ],
+    isError: true
+  };
+};
 
 // ../../node_modules/.pnpm/zod@4.3.5/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -17298,7 +17431,13 @@ var startMcpServer = async () => {
   server.registerTool(
     "browser_snapshot",
     {
-      description: `Get ARIA accessibility tree with element refs (e1, e2...).
+      description: `Get ARIA accessibility tree with element refs (e1, e2...) and React component info.
+
+OUTPUT INCLUDES:
+- ARIA roles and accessible names
+- Element refs (e1, e2...) for interaction
+- [component=ComponentName] for React components
+- [source=file.tsx:line] for source location
 
 SCREENSHOT STRATEGY - ALWAYS prefer element screenshots over full page:
 1. First: Get refs with snapshot (this tool)
@@ -17316,7 +17455,7 @@ USE VIEWPORT screenshot=true ONLY FOR:
 
 PERFORMANCE:
 - interactableOnly:true = much smaller output (recommended)
-- format:'compact' = minimal ref:role:name output
+- format:'compact' = minimal ref:role:name@Component output
 - maxDepth = limit tree depth
 
 After getting refs, use browser_execute with: ref('e1').click()`,
@@ -17337,16 +17476,11 @@ After getting refs, use browser_execute with: ref('e1').click()`,
       format,
       screenshot
     }) => {
-      let activePage = null;
       let browser2 = null;
       try {
-        const { serverUrl } = await ensureHealthyServer();
-        const pageInfo = await getOrCreatePage(serverUrl, pageName);
-        browser2 = await playwrightCore.chromium.connectOverCDP(pageInfo.wsEndpoint);
-        activePage = await browser$1.findPageByTargetId(browser2, pageInfo.targetId);
-        if (!activePage) {
-          throw new Error(`Page "${pageName}" not found`);
-        }
+        const connection = await connectToBrowserPage(pageName);
+        browser2 = connection.browser;
+        const activePage = connection.page;
         const getActivePage2 = () => activePage;
         const snapshot = createSnapshotHelper(getActivePage2);
         const snapshotResult = await snapshot({ maxDepth, interactableOnly, format });
@@ -17370,18 +17504,7 @@ After getting refs, use browser_execute with: ref('e1').click()`,
           content: [{ type: "text", text: snapshotResult }]
         };
       } catch (error48) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                ok: false,
-                error: error48 instanceof Error ? error48.message : "Failed"
-              })
-            }
-          ],
-          isError: true
-        };
+        return createMcpErrorResponse(error48);
       } finally {
         await browser2?.close();
       }
@@ -17396,25 +17519,32 @@ IMPORTANT: Always call snapshot() first to get element refs from the a11y tree (
 
 AVAILABLE HELPERS:
 - page: Playwright Page object (https://playwright.dev/docs/api/class-page)
-- snapshot(opts?): Get ARIA tree. opts: {maxDepth, interactableOnly, format}
+- snapshot(opts?): Get ARIA tree with React component info. opts: {maxDepth, interactableOnly, format}
 - ref(id): Get element by ref ID, chainable with all ElementHandle methods
+- ref(id).source(): Get React component source {filePath, lineNumber, componentName}
+- ref(id).props(): Get React component props (serialized)
+- ref(id).state(): Get React component state/hooks (serialized)
+- component(name, opts?): Find elements by React component name. opts: {nth: number}
 - fill(id, text): Clear and fill input (works with rich text editors)
 - drag({from, to, dataTransfer?}): Drag with custom MIME types
 - dispatch({target, event, dataTransfer?, detail?}): Dispatch custom events
 - waitFor(target): Wait for selector/ref/state. e.g. waitFor('e1'), waitFor('networkidle')
 - grab: React Grab client API (activate, deactivate, toggle, isActive, copyElement, getState)
 
+REACT-SPECIFIC PATTERNS:
+- Get React source: return await ref('e1').source()
+- Get component props: return await ref('e1').props()
+- Get component state: return await ref('e1').state()
+- Find by component: const btn = await component('Button', {nth: 0})
+
 ELEMENT SCREENSHOTS (PREFERRED for visual issues):
 - return await ref('e1').screenshot()
-- return await ref('e2').screenshot()
 Use for: wrong color, broken styling, visual bugs, "how does X look", UI verification
-Returns image directly - no file path needed.
 
 COMMON PATTERNS:
 - Click: await ref('e1').click()
 - Fill input: await fill('e1', 'hello')
 - Get attribute: return await ref('e1').getAttribute('href')
-- Get React source: return await ref('e1').source()
 - Navigate: await page.goto('https://example.com')
 - Full page screenshot (rare): return await page.screenshot()
 
@@ -17434,13 +17564,9 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
       let pageOpenHandler = null;
       const outputJson = createOutputJson(() => activePage, pageName);
       try {
-        const { serverUrl } = await ensureHealthyServer();
-        const pageInfo = await getOrCreatePage(serverUrl, pageName);
-        browser2 = await playwrightCore.chromium.connectOverCDP(pageInfo.wsEndpoint);
-        activePage = await browser$1.findPageByTargetId(browser2, pageInfo.targetId);
-        if (!activePage) {
-          throw new Error(`Page "${pageName}" not found`);
-        }
+        const connection = await connectToBrowserPage(pageName);
+        browser2 = connection.browser;
+        activePage = connection.page;
         if (url2) {
           await activePage.goto(url2, {
             waitUntil: "domcontentloaded",
@@ -17460,6 +17586,7 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
         const dispatch = createDispatchHelper(getActivePage2);
         const grab = createGrabHelper(ref, getActivePage2);
         const waitFor = createWaitForHelper(getActivePage2);
+        const component = createComponentHelper(getActivePage2);
         const executeFunction = new Function(
           "page",
           "getActivePage",
@@ -17470,6 +17597,7 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
           "dispatch",
           "grab",
           "waitFor",
+          "component",
           `return (async () => { ${code} })();`
         );
         const result = await executeFunction(
@@ -17481,7 +17609,8 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
           drag,
           dispatch,
           grab,
-          waitFor
+          waitFor,
+          component
         );
         if (Buffer.isBuffer(result)) {
           const output2 = await outputJson(true, void 0);
@@ -17518,12 +17647,82 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
       }
     }
   );
+  server.registerTool(
+    "browser_react_tree",
+    {
+      description: `Get React component tree hierarchy (separate from ARIA tree).
+
+Shows the React component structure with:
+- Component names and nesting
+- Source file locations
+- Element refs where available
+- Optional props (serialized)
+
+Use this when you need to understand React component architecture rather than accessibility tree.
+For interacting with elements, use browser_snapshot to get refs first.`,
+      inputSchema: {
+        page: external_exports.string().optional().default("default").describe("Named page context"),
+        maxDepth: external_exports.number().optional().default(50).describe("Maximum tree depth"),
+        includeProps: external_exports.boolean().optional().default(false).describe("Include component props (increases output size)")
+      }
+    },
+    async ({ page: pageName, maxDepth, includeProps }) => {
+      let browser2 = null;
+      try {
+        const connection = await connectToBrowserPage(pageName);
+        browser2 = connection.browser;
+        const activePage = connection.page;
+        const componentTree = await activePage.evaluate(
+          async (opts2) => {
+            const g2 = globalThis;
+            if (!g2.__REACT_GRAB_GET_COMPONENT_TREE__) {
+              return [];
+            }
+            return g2.__REACT_GRAB_GET_COMPONENT_TREE__(opts2);
+          },
+          { maxDepth: maxDepth ?? 50, includeProps: includeProps ?? false }
+        );
+        const renderTree = (nodes) => {
+          const lines = [];
+          for (const node of nodes) {
+            const indent = "  ".repeat(node.depth);
+            let line = `${indent}- ${node.name}`;
+            if (node.ref) line += ` [ref=${node.ref}]`;
+            if (node.source) line += ` [source=${node.source}]`;
+            if (node.props && Object.keys(node.props).length > 0) {
+              const propsStr = JSON.stringify(node.props);
+              if (propsStr.length < 100) {
+                line += ` [props=${propsStr}]`;
+              } else {
+                line += ` [props=...]`;
+              }
+            }
+            lines.push(line);
+          }
+          return lines.join("\n");
+        };
+        const treeOutput = renderTree(componentTree);
+        return {
+          content: [
+            {
+              type: "text",
+              text: treeOutput || "No React components found. Make sure react-grab is installed and the page uses React."
+            }
+          ]
+        };
+      } catch (error48) {
+        return createMcpErrorResponse(error48);
+      } finally {
+        await browser2?.close();
+      }
+    }
+  );
   const transport = new stdio_js.StdioServerTransport();
   await server.connect(transport);
 };
 
 // src/commands/browser.ts
-var VERSION2 = "0.1.0-beta.2";
+var VERSION2 = "0.1.0-beta.3";
 var printHeader = () => {
   console.log(
     `${pc__default.default.magenta("\u273F")} ${pc__default.default.bold("React Grab")} ${pc__default.default.gray(VERSION2)}`
@@ -18011,14 +18210,7 @@ browser.addCommand(status);
 browser.addCommand(execute);
 browser.addCommand(pages);
 browser.addCommand(mcp);
-
-// src/utils/constants.ts
-var MAX_SUGGESTIONS_COUNT = 30;
-var MAX_KEY_HOLD_DURATION_MS = 2e3;
-var MAX_CONTEXT_LINES = 50;
-
-// src/commands/configure.ts
-var VERSION3 = "0.1.0-beta.2";
+var VERSION3 = "0.1.0-beta.3";
 var isMac = process.platform === "darwin";
 var META_LABEL = isMac ? "Cmd" : "Win";
 var ALT_LABEL = isMac ? "Option" : "Alt";
@@ -18505,7 +18697,7 @@ var uninstallPackagesWithFeedback = (packages, packageManager, projectRoot) => {
     handleError(error48);
   }
 };
-var VERSION4 = "0.1.0-beta.2";
+var VERSION4 = "0.1.0-beta.3";
 var REPORT_URL = "https://react-grab.com/api/report-cli";
 var DOCS_URL = "https://github.com/aidenybai/react-grab";
 var promptAgentIntegration = async (cwd, customPkg) => {
@@ -19197,7 +19389,7 @@ var init = new commander.Command().name("init").description("initialize React Gr
     await reportToCli("error", void 0, error48);
   }
 });
-var VERSION5 = "0.1.0-beta.2";
+var VERSION5 = "0.1.0-beta.3";
 var remove = new commander.Command().name("remove").description("remove an agent integration").argument(
   "[agent]",
   "agent to remove (claude-code, cursor, opencode, codex, gemini, amp, ami, visual-edit)"
@@ -19376,7 +19568,7 @@ var remove = new commander.Command().name("remove").description("remove an agent
 });
 
 // src/cli.ts
-var VERSION6 = "0.1.0-beta.2";
+var VERSION6 = "0.1.0-beta.3";
 var VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));

package/dist/cli.js

@@ -2697,7 +2697,7 @@ var previewPackageJsonAgentRemoval = (projectRoot, agent) => {
 };
 
 // src/commands/add.ts
-var VERSION = "0.1.0-beta.2";
+var VERSION = "0.1.0-beta.3";
 var add = new Command().name("add").alias("install").description("add an agent integration or MCP server").argument(
   "[agent]",
   `agent to add (${AGENTS.join(", ")}, mcp, skill)`
@@ -3226,6 +3226,15 @@ var add = new Command().name("add").alias("install").description("add an agent i
     handleError(error48);
   }
 });
+
+// src/utils/constants.ts
+var MAX_SUGGESTIONS_COUNT = 30;
+var MAX_KEY_HOLD_DURATION_MS = 2e3;
+var MAX_CONTEXT_LINES = 50;
+var COMPONENT_STACK_MAX_DEPTH = 10;
+
+// src/utils/browser-automation.ts
+var LOAD_STATES = /* @__PURE__ */ new Set(["load", "domcontentloaded", "networkidle"]);
 var ensureHealthyServer = async (options2 = {}) => {
   const cliPath = process.argv[1];
   const serverRunning = await isServerRunning();
@@ -3256,16 +3265,65 @@ var getOrCreatePage = async (serverUrl, name) => {
   }
   return response.json();
 };
+var getReactContextForActiveElement = async (page) => {
+  try {
+    return page.evaluate(async (maxDepth) => {
+      const activeElement = document.activeElement;
+      if (!activeElement || activeElement === document.body) return null;
+      const reactGrab = globalThis.__REACT_GRAB__;
+      if (!reactGrab?.getSource) return null;
+      const source = await reactGrab.getSource(activeElement);
+      if (!source) return null;
+      const componentStack = [];
+      if (source.componentName) {
+        componentStack.push(source.componentName);
+      }
+      const fiberKey = Object.keys(activeElement).find(
+        (key) => key.startsWith("__reactFiber$") || key.startsWith("__reactInternalInstance$")
+      );
+      if (fiberKey) {
+        let fiber = activeElement[fiberKey];
+        let depth = 0;
+        while (fiber?.return && depth < maxDepth) {
+          fiber = fiber.return;
+          if (fiber.tag === 0 || fiber.tag === 1 || fiber.tag === 11) {
+            const name = typeof fiber.type === "object" ? fiber.type?.displayName || fiber.type?.name : null;
+            if (name && !name.startsWith("_") && !componentStack.includes(name)) {
+              componentStack.push(name);
+            }
+          }
+          depth++;
+        }
+      }
+      return {
+        element: activeElement.tagName.toLowerCase(),
+        component: source.componentName || void 0,
+        source: source.filePath ? `${source.filePath}${source.lineNumber ? `:${source.lineNumber}` : ""}` : void 0,
+        componentStack: componentStack.length > 0 ? componentStack : void 0
+      };
+    }, COMPONENT_STACK_MAX_DEPTH);
+  } catch {
+    return null;
+  }
+};
 var createOutputJson = (getPage, pageName) => {
   return async (ok, result, error48) => {
     const page = getPage();
+    let reactContext;
+    if (page && ok) {
+      const context = await getReactContextForActiveElement(page);
+      if (context) {
+        reactContext = context;
+      }
+    }
     return {
       ok,
       url: page?.url() ?? "",
       title: page ? await page.title().catch(() => "") : "",
       page: pageName,
       ...result !== void 0 && { result },
-      ...error48 && { error: error48 }
+      ...error48 && { error: error48 },
+      ...reactContext && { reactContext }
     };
   };
 };
@@ -3324,6 +3382,24 @@ var createRefHelper = (getActivePage2) => {
       return g2.__REACT_GRAB__.getSource(el);
     }, element);
   };
+  const getProps = async (refId) => {
+    const element = await getElement(refId);
+    const currentPage2 = getActivePage2();
+    return currentPage2.evaluate((el) => {
+      const g2 = globalThis;
+      if (!g2.__REACT_GRAB_GET_PROPS__) return null;
+      return g2.__REACT_GRAB_GET_PROPS__(el);
+    }, element);
+  };
+  const getState = async (refId) => {
+    const element = await getElement(refId);
+    const currentPage2 = getActivePage2();
+    return currentPage2.evaluate((el) => {
+      const g2 = globalThis;
+      if (!g2.__REACT_GRAB_GET_STATE__) return null;
+      return g2.__REACT_GRAB_GET_STATE__(el);
+    }, element);
+  };
   return (refId) => {
     return new Proxy(
       {},
@@ -3335,6 +3411,12 @@ var createRefHelper = (getActivePage2) => {
           if (prop === "source") {
             return () => getSource(refId);
           }
+          if (prop === "props") {
+            return () => getProps(refId);
+          }
+          if (prop === "state") {
+            return () => getState(refId);
+          }
           if (prop === "screenshot") {
             return (options2) => getElement(refId).then(
               (el) => el.screenshot({ scale: "css", ...options2 })
@@ -3348,6 +3430,50 @@ var createRefHelper = (getActivePage2) => {
     );
   };
 };
+var createComponentHelper = (getActivePage2) => {
+  return async (componentName, options2) => {
+    const currentPage2 = getActivePage2();
+    const nth = options2?.nth;
+    const elementHandles = await currentPage2.evaluateHandle(
+      async (args) => {
+        const g2 = globalThis;
+        if (!g2.__REACT_GRAB_FIND_BY_COMPONENT__) {
+          throw new Error("React introspection not available. Make sure react-grab is installed.");
+        }
+        const result = await g2.__REACT_GRAB_FIND_BY_COMPONENT__(args.name, args.nth !== void 0 ? { nth: args.nth } : void 0);
+        if (!result) return null;
+        if (args.nth !== void 0) {
+          const single = result;
+          return single?.element || null;
+        }
+        const arr = result;
+        return arr.map((m2) => m2.element);
+      },
+      { name: componentName, nth }
+    );
+    const value = await elementHandles.jsonValue().catch(() => null);
+    if (value === null) {
+      await elementHandles.dispose();
+      return null;
+    }
+    if (nth !== void 0) {
+      const element = elementHandles.asElement();
+      if (!element) {
+        await elementHandles.dispose();
+        return null;
+      }
+      return element;
+    }
+    const jsHandles = await elementHandles.getProperties();
+    const handles = [];
+    for (const [, handle] of jsHandles) {
+      const element = handle.asElement();
+      if (element) handles.push(element);
+    }
+    await elementHandles.dispose();
+    return handles;
+  };
+};
 var createFillHelper = (ref, getActivePage2) => {
   return async (refId, text) => {
     const element = await ref(refId);
@@ -3449,35 +3575,22 @@ var createDispatchHelper = (getActivePage2) => {
   };
 };
 var createGrabHelper = (ref, getActivePage2) => {
+  const evaluateGrabMethod = async (methodName, defaultValue) => {
+    const currentPage2 = getActivePage2();
+    return currentPage2.evaluate(
+      ({ method, fallback }) => {
+        const grab = globalThis.__REACT_GRAB__;
+        return grab?.[method]?.() ?? fallback;
+      },
+      { method: methodName, fallback: defaultValue }
+    );
+  };
   return {
-    activate: async () => {
-      const currentPage2 = getActivePage2();
-      await currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        g2.__REACT_GRAB__?.activate();
-      });
-    },
-    deactivate: async () => {
-      const currentPage2 = getActivePage2();
-      await currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        g2.__REACT_GRAB__?.deactivate();
-      });
-    },
-    toggle: async () => {
-      const currentPage2 = getActivePage2();
-      await currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        g2.__REACT_GRAB__?.toggle();
-      });
-    },
-    isActive: async () => {
-      const currentPage2 = getActivePage2();
-      return currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        return g2.__REACT_GRAB__?.isActive() ?? false;
-      });
-    },
+    activate: () => evaluateGrabMethod("activate", void 0),
+    deactivate: () => evaluateGrabMethod("deactivate", void 0),
+    toggle: () => evaluateGrabMethod("toggle", void 0),
+    isActive: () => evaluateGrabMethod("isActive", false),
+    getState: () => evaluateGrabMethod("getState", null),
     copyElement: async (refId) => {
       const element = await ref(refId);
       if (!element) return false;
@@ -3486,13 +3599,6 @@ var createGrabHelper = (ref, getActivePage2) => {
         const g2 = globalThis;
         return g2.__REACT_GRAB__?.copyElement([el]) ?? false;
       }, element);
-    },
-    getState: async () => {
-      const currentPage2 = getActivePage2();
-      return currentPage2.evaluate(() => {
-        const g2 = globalThis;
-        return g2.__REACT_GRAB__?.getState() ?? null;
-      });
     }
   };
 };
@@ -3508,7 +3614,7 @@ var createWaitForHelper = (getActivePage2) => {
   return async (selectorOrState, options2) => {
     const currentPage2 = getActivePage2();
     const timeout = options2?.timeout;
-    if (selectorOrState === "load" || selectorOrState === "domcontentloaded" || selectorOrState === "networkidle") {
+    if (LOAD_STATES.has(selectorOrState)) {
       await currentPage2.waitForLoadState(selectorOrState, { timeout });
       return;
     }
@@ -3519,6 +3625,33 @@ var createWaitForHelper = (getActivePage2) => {
     await currentPage2.waitForSelector(selectorOrState, { timeout });
   };
 };
+var connectToBrowserPage = async (pageName) => {
+  const { chromium: chromium2 } = await import('playwright-core');
+  const { findPageByTargetId: findPageByTargetId2 } = await import('@react-grab/browser');
+  const { serverUrl } = await ensureHealthyServer();
+  const pageInfo = await getOrCreatePage(serverUrl, pageName);
+  const browser2 = await chromium2.connectOverCDP(pageInfo.wsEndpoint);
+  const page = await findPageByTargetId2(browser2, pageInfo.targetId);
+  if (!page) {
+    await browser2.close();
+    throw new Error(`Page "${pageName}" not found`);
+  }
+  return { browser: browser2, page, serverUrl };
+};
+var createMcpErrorResponse = (error48) => {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          ok: false,
+          error: error48 instanceof Error ? error48.message : "Failed"
+        })
+      }
+    ],
+    isError: true
+  };
+};
 
 // ../../node_modules/.pnpm/zod@4.3.5/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -17288,7 +17421,13 @@ var startMcpServer = async () => {
   server.registerTool(
     "browser_snapshot",
     {
-      description: `Get ARIA accessibility tree with element refs (e1, e2...).
+      description: `Get ARIA accessibility tree with element refs (e1, e2...) and React component info.
+
+OUTPUT INCLUDES:
+- ARIA roles and accessible names
+- Element refs (e1, e2...) for interaction
+- [component=ComponentName] for React components
+- [source=file.tsx:line] for source location
 
 SCREENSHOT STRATEGY - ALWAYS prefer element screenshots over full page:
 1. First: Get refs with snapshot (this tool)
@@ -17306,7 +17445,7 @@ USE VIEWPORT screenshot=true ONLY FOR:
 
 PERFORMANCE:
 - interactableOnly:true = much smaller output (recommended)
-- format:'compact' = minimal ref:role:name output
+- format:'compact' = minimal ref:role:name@Component output
 - maxDepth = limit tree depth
 
 After getting refs, use browser_execute with: ref('e1').click()`,
@@ -17327,16 +17466,11 @@ After getting refs, use browser_execute with: ref('e1').click()`,
       format,
       screenshot
     }) => {
-      let activePage = null;
       let browser2 = null;
       try {
-        const { serverUrl } = await ensureHealthyServer();
-        const pageInfo = await getOrCreatePage(serverUrl, pageName);
-        browser2 = await chromium.connectOverCDP(pageInfo.wsEndpoint);
-        activePage = await findPageByTargetId(browser2, pageInfo.targetId);
-        if (!activePage) {
-          throw new Error(`Page "${pageName}" not found`);
-        }
+        const connection = await connectToBrowserPage(pageName);
+        browser2 = connection.browser;
+        const activePage = connection.page;
         const getActivePage2 = () => activePage;
         const snapshot = createSnapshotHelper(getActivePage2);
         const snapshotResult = await snapshot({ maxDepth, interactableOnly, format });
@@ -17360,18 +17494,7 @@ After getting refs, use browser_execute with: ref('e1').click()`,
           content: [{ type: "text", text: snapshotResult }]
         };
       } catch (error48) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                ok: false,
-                error: error48 instanceof Error ? error48.message : "Failed"
-              })
-            }
-          ],
-          isError: true
-        };
+        return createMcpErrorResponse(error48);
       } finally {
         await browser2?.close();
       }
@@ -17386,25 +17509,32 @@ IMPORTANT: Always call snapshot() first to get element refs from the a11y tree (
 
 AVAILABLE HELPERS:
 - page: Playwright Page object (https://playwright.dev/docs/api/class-page)
-- snapshot(opts?): Get ARIA tree. opts: {maxDepth, interactableOnly, format}
+- snapshot(opts?): Get ARIA tree with React component info. opts: {maxDepth, interactableOnly, format}
 - ref(id): Get element by ref ID, chainable with all ElementHandle methods
+- ref(id).source(): Get React component source {filePath, lineNumber, componentName}
+- ref(id).props(): Get React component props (serialized)
+- ref(id).state(): Get React component state/hooks (serialized)
+- component(name, opts?): Find elements by React component name. opts: {nth: number}
 - fill(id, text): Clear and fill input (works with rich text editors)
 - drag({from, to, dataTransfer?}): Drag with custom MIME types
 - dispatch({target, event, dataTransfer?, detail?}): Dispatch custom events
 - waitFor(target): Wait for selector/ref/state. e.g. waitFor('e1'), waitFor('networkidle')
 - grab: React Grab client API (activate, deactivate, toggle, isActive, copyElement, getState)
 
+REACT-SPECIFIC PATTERNS:
+- Get React source: return await ref('e1').source()
+- Get component props: return await ref('e1').props()
+- Get component state: return await ref('e1').state()
+- Find by component: const btn = await component('Button', {nth: 0})
+
 ELEMENT SCREENSHOTS (PREFERRED for visual issues):
 - return await ref('e1').screenshot()
-- return await ref('e2').screenshot()
 Use for: wrong color, broken styling, visual bugs, "how does X look", UI verification
-Returns image directly - no file path needed.
 
 COMMON PATTERNS:
 - Click: await ref('e1').click()
 - Fill input: await fill('e1', 'hello')
 - Get attribute: return await ref('e1').getAttribute('href')
-- Get React source: return await ref('e1').source()
 - Navigate: await page.goto('https://example.com')
 - Full page screenshot (rare): return await page.screenshot()
 
@@ -17424,13 +17554,9 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
       let pageOpenHandler = null;
       const outputJson = createOutputJson(() => activePage, pageName);
       try {
-        const { serverUrl } = await ensureHealthyServer();
-        const pageInfo = await getOrCreatePage(serverUrl, pageName);
-        browser2 = await chromium.connectOverCDP(pageInfo.wsEndpoint);
-        activePage = await findPageByTargetId(browser2, pageInfo.targetId);
-        if (!activePage) {
-          throw new Error(`Page "${pageName}" not found`);
-        }
+        const connection = await connectToBrowserPage(pageName);
+        browser2 = connection.browser;
+        activePage = connection.page;
         if (url2) {
           await activePage.goto(url2, {
             waitUntil: "domcontentloaded",
@@ -17450,6 +17576,7 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
         const dispatch = createDispatchHelper(getActivePage2);
         const grab = createGrabHelper(ref, getActivePage2);
         const waitFor = createWaitForHelper(getActivePage2);
+        const component = createComponentHelper(getActivePage2);
         const executeFunction = new Function(
           "page",
           "getActivePage",
@@ -17460,6 +17587,7 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
           "dispatch",
           "grab",
           "waitFor",
+          "component",
           `return (async () => { ${code} })();`
         );
         const result = await executeFunction(
@@ -17471,7 +17599,8 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
           drag,
           dispatch,
           grab,
-          waitFor
+          waitFor,
+          component
         );
         if (Buffer.isBuffer(result)) {
           const output2 = await outputJson(true, void 0);
@@ -17508,12 +17637,82 @@ PERFORMANCE: Batch multiple actions in one execute call to minimize round-trips.
       }
     }
   );
+  server.registerTool(
+    "browser_react_tree",
+    {
+      description: `Get React component tree hierarchy (separate from ARIA tree).
+
+Shows the React component structure with:
+- Component names and nesting
+- Source file locations
+- Element refs where available
+- Optional props (serialized)
+
+Use this when you need to understand React component architecture rather than accessibility tree.
+For interacting with elements, use browser_snapshot to get refs first.`,
+      inputSchema: {
+        page: external_exports.string().optional().default("default").describe("Named page context"),
+        maxDepth: external_exports.number().optional().default(50).describe("Maximum tree depth"),
+        includeProps: external_exports.boolean().optional().default(false).describe("Include component props (increases output size)")
+      }
+    },
+    async ({ page: pageName, maxDepth, includeProps }) => {
+      let browser2 = null;
+      try {
+        const connection = await connectToBrowserPage(pageName);
+        browser2 = connection.browser;
+        const activePage = connection.page;
+        const componentTree = await activePage.evaluate(
+          async (opts2) => {
+            const g2 = globalThis;
+            if (!g2.__REACT_GRAB_GET_COMPONENT_TREE__) {
+              return [];
+            }
+            return g2.__REACT_GRAB_GET_COMPONENT_TREE__(opts2);
+          },
+          { maxDepth: maxDepth ?? 50, includeProps: includeProps ?? false }
+        );
+        const renderTree = (nodes) => {
+          const lines = [];
+          for (const node of nodes) {
+            const indent = "  ".repeat(node.depth);
+            let line = `${indent}- ${node.name}`;
+            if (node.ref) line += ` [ref=${node.ref}]`;
+            if (node.source) line += ` [source=${node.source}]`;
+            if (node.props && Object.keys(node.props).length > 0) {
+              const propsStr = JSON.stringify(node.props);
+              if (propsStr.length < 100) {
+                line += ` [props=${propsStr}]`;
+              } else {
+                line += ` [props=...]`;
+              }
+            }
+            lines.push(line);
+          }
+          return lines.join("\n");
+        };
+        const treeOutput = renderTree(componentTree);
+        return {
+          content: [
+            {
+              type: "text",
+              text: treeOutput || "No React components found. Make sure react-grab is installed and the page uses React."
+            }
+          ]
+        };
+      } catch (error48) {
+        return createMcpErrorResponse(error48);
+      } finally {
+        await browser2?.close();
+      }
+    }
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 };
 
 // src/commands/browser.ts
-var VERSION2 = "0.1.0-beta.2";
+var VERSION2 = "0.1.0-beta.3";
 var printHeader = () => {
   console.log(
     `${pc.magenta("\u273F")} ${pc.bold("React Grab")} ${pc.gray(VERSION2)}`
@@ -18001,14 +18200,7 @@ browser.addCommand(status);
 browser.addCommand(execute);
 browser.addCommand(pages);
 browser.addCommand(mcp);
-
-// src/utils/constants.ts
-var MAX_SUGGESTIONS_COUNT = 30;
-var MAX_KEY_HOLD_DURATION_MS = 2e3;
-var MAX_CONTEXT_LINES = 50;
-
-// src/commands/configure.ts
-var VERSION3 = "0.1.0-beta.2";
+var VERSION3 = "0.1.0-beta.3";
 var isMac = process.platform === "darwin";
 var META_LABEL = isMac ? "Cmd" : "Win";
 var ALT_LABEL = isMac ? "Option" : "Alt";
@@ -18495,7 +18687,7 @@ var uninstallPackagesWithFeedback = (packages, packageManager, projectRoot) => {
     handleError(error48);
   }
 };
-var VERSION4 = "0.1.0-beta.2";
+var VERSION4 = "0.1.0-beta.3";
 var REPORT_URL = "https://react-grab.com/api/report-cli";
 var DOCS_URL = "https://github.com/aidenybai/react-grab";
 var promptAgentIntegration = async (cwd, customPkg) => {
@@ -19187,7 +19379,7 @@ var init = new Command().name("init").description("initialize React Grab in your
     await reportToCli("error", void 0, error48);
   }
 });
-var VERSION5 = "0.1.0-beta.2";
+var VERSION5 = "0.1.0-beta.3";
 var remove = new Command().name("remove").description("remove an agent integration").argument(
   "[agent]",
   "agent to remove (claude-code, cursor, opencode, codex, gemini, amp, ami, visual-edit)"
@@ -19366,7 +19558,7 @@ var remove = new Command().name("remove").description("remove an agent integrati
 });
 
 // src/cli.ts
-var VERSION6 = "0.1.0-beta.2";
+var VERSION6 = "0.1.0-beta.3";
 var VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-grab/cli",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "type": "module",
   "bin": {
     "react-grab": "./dist/cli.js"
@@ -32,7 +32,7 @@
     "playwright-core": "^1.50.0",
     "prompts": "^2.4.2",
     "zod": "^4.3.5",
-    "@react-grab/browser": "0.1.0-beta.2"
+    "@react-grab/browser": "0.1.0-beta.4"
   },
   "scripts": {
     "dev": "tsup --watch",