@react-grab/cli 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/cli.cjs

@@ -2707,7 +2707,7 @@ var previewPackageJsonAgentRemoval = (projectRoot, agent) => {
 };
 
 // src/commands/add.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.0-beta.4";
 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 }
     };
   };
 };
@@ -3327,12 +3385,42 @@ var createRefHelper = (getActivePage2) => {
   };
   const getSource = async (refId) => {
     const element = await getElement(refId);
-    const currentPage2 = getActivePage2();
-    return currentPage2.evaluate((el) => {
-      const g2 = globalThis;
-      if (!g2.__REACT_GRAB__) return null;
-      return g2.__REACT_GRAB__.getSource(el);
-    }, element);
+    try {
+      const currentPage2 = getActivePage2();
+      return await currentPage2.evaluate((el) => {
+        const g2 = globalThis;
+        if (!g2.__REACT_GRAB__) return null;
+        return g2.__REACT_GRAB__.getSource(el);
+      }, element);
+    } finally {
+      await element.dispose();
+    }
+  };
+  const getProps = async (refId) => {
+    const element = await getElement(refId);
+    try {
+      const currentPage2 = getActivePage2();
+      return await currentPage2.evaluate((el) => {
+        const g2 = globalThis;
+        if (!g2.__REACT_GRAB_GET_PROPS__) return null;
+        return g2.__REACT_GRAB_GET_PROPS__(el);
+      }, element);
+    } finally {
+      await element.dispose();
+    }
+  };
+  const getState = async (refId) => {
+    const element = await getElement(refId);
+    try {
+      const currentPage2 = getActivePage2();
+      return await currentPage2.evaluate((el) => {
+        const g2 = globalThis;
+        if (!g2.__REACT_GRAB_GET_STATE__) return null;
+        return g2.__REACT_GRAB_GET_STATE__(el);
+      }, element);
+    } finally {
+      await element.dispose();
+    }
   };
   return (refId) => {
     return new Proxy(
@@ -3345,19 +3433,79 @@ 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 })
-            );
+            return async (options2) => {
+              const el = await getElement(refId);
+              try {
+                return await el.screenshot({ scale: "css", ...options2 });
+              } finally {
+                await el.dispose();
+              }
+            };
           }
-          return (...args) => getElement(refId).then(
-            (el) => el[prop](...args)
-          );
+          return async (...args) => {
+            const el = await getElement(refId);
+            try {
+              return await el[prop](...args);
+            } finally {
+              await el.dispose();
+            }
+          };
         }
       }
     );
   };
 };
+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 isNull = await currentPage2.evaluate((value) => value === null, elementHandles);
+    if (isNull) {
+      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,50 +3607,34 @@ 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;
-      const currentPage2 = getActivePage2();
-      return currentPage2.evaluate((el) => {
-        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;
-      });
+      try {
+        const currentPage2 = getActivePage2();
+        return await currentPage2.evaluate((el) => {
+          const g2 = globalThis;
+          return g2.__REACT_GRAB__?.copyElement([el]) ?? false;
+        }, element);
+      } finally {
+        await element.dispose();
+      }
     }
   };
 };
@@ -3518,7 +3650,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 +3661,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 +17457,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 +17481,6 @@ USE VIEWPORT screenshot=true ONLY FOR:
 
 PERFORMANCE:
 - interactableOnly:true = much smaller output (recommended)
-- format:'compact' = minimal ref:role:name output
 - maxDepth = limit tree depth
 
 After getting refs, use browser_execute with: ref('e1').click()`,
@@ -17324,7 +17488,6 @@ After getting refs, use browser_execute with: ref('e1').click()`,
         page: external_exports.string().optional().default("default").describe("Named page context"),
         maxDepth: external_exports.number().optional().describe("Limit tree depth"),
         interactableOnly: external_exports.boolean().optional().describe("Only clickable/input elements (recommended)"),
-        format: external_exports.enum(["yaml", "compact"]).optional().default("yaml").describe("'yaml' or 'compact'"),
         screenshot: external_exports.boolean().optional().default(false).describe(
           "Viewport screenshot. For element screenshots (PREFERRED), use browser_execute: ref('eX').screenshot()"
         )
@@ -17334,22 +17497,16 @@ After getting refs, use browser_execute with: ref('e1').click()`,
       page: pageName,
       maxDepth,
       interactableOnly,
-      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 });
+        const snapshotResult = await snapshot({ maxDepth, interactableOnly });
         if (screenshot) {
           const screenshotBuffer = await activePage.screenshot({
             fullPage: false,
@@ -17370,18 +17527,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 +17542,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}
 - 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 +17587,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 +17609,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 +17620,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 +17632,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 +17670,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";
+var VERSION2 = "0.1.0-beta.4";
 var printHeader = () => {
   console.log(
     `${pc__default.default.magenta("\u273F")} ${pc__default.default.bold("React Grab")} ${pc__default.default.gray(VERSION2)}`
@@ -17546,6 +17768,10 @@ var rebuildNativeModuleAndRestart = async (browserPkgDir) => {
     stdio: "inherit",
     detached: false
   });
+  child.on("error", (error48) => {
+    console.error(`Failed to restart: ${error48.message}`);
+    process.exit(1);
+  });
   child.on("exit", (code) => process.exit(code ?? 0));
 };
 var isSupportedBrowser = (value) => {
@@ -17644,8 +17870,10 @@ var start = new commander.Command().name("start").description("start browser ser
       const playwrightCookies = browser$1.toPlaywrightCookies(cookies);
       const browser2 = await playwrightCore.chromium.connectOverCDP(browserServer.wsEndpoint);
       const contexts = browser2.contexts();
-      if (contexts.length > 0 && playwrightCookies.length > 0) {
-        await contexts[0].addCookies(playwrightCookies);
+      if (contexts.length > 0) {
+        if (playwrightCookies.length > 0) {
+          await contexts[0].addCookies(playwrightCookies);
+        }
         await browser$1.applyStealthScripts(contexts[0]);
       }
       await browser2.close();
@@ -17777,6 +18005,7 @@ var execute = new commander.Command().name("execute").description("run Playwrigh
     const dispatch = createDispatchHelper(getActivePage2);
     const grab = createGrabHelper(ref, getActivePage2);
     const waitFor = createWaitForHelper(getActivePage2);
+    const component = createComponentHelper(getActivePage2);
     const executeFunction = new Function(
       "page",
       "getActivePage",
@@ -17787,9 +18016,10 @@ var execute = new commander.Command().name("execute").description("run Playwrigh
       "dispatch",
       "grab",
       "waitFor",
+      "component",
       `return (async () => { ${code} })();`
     );
-    const result = await executeFunction(getActivePage2(), getActivePage2, snapshot, ref, fill, drag, dispatch, grab, waitFor);
+    const result = await executeFunction(getActivePage2(), getActivePage2, snapshot, ref, fill, drag, dispatch, grab, waitFor, component);
     console.log(JSON.stringify(await buildOutput(true, result)));
   } catch (error48) {
     console.log(JSON.stringify(await buildOutput(false, void 0, error48 instanceof Error ? error48.message : "Failed")));
@@ -17847,8 +18077,7 @@ PERFORMANCE TIPS
   1. Batch multiple actions in a single execute call to minimize round-trips.
      Each execute spawns a new connection, so combining actions is 3-5x faster.
 
-  2. Use compact format or limit depth for smaller snapshots (faster, fewer tokens).
-     - snapshot({format: 'compact'})      -> minimal ref:role:name output
+  2. Use interactableOnly or limit depth for smaller snapshots (faster, fewer tokens).
      - snapshot({interactableOnly: true}) -> only clickable/input elements
      - snapshot({maxDepth: 5})            -> limit tree depth
 
@@ -17857,22 +18086,28 @@ PERFORMANCE TIPS
   execute "await ref('e1').click()"
   execute "return await snapshot()"
 
-  # FAST: 1 round-trip, compact output
+  # FAST: 1 round-trip, interactable only
   execute "
     await page.goto('https://example.com');
     await ref('e1').click();
-    return await snapshot({format: 'compact'});
+    return await snapshot({interactableOnly: true});
   "
 
 HELPERS
   page              - Playwright Page object
   snapshot(opts?)   - Get ARIA accessibility tree with refs
                       opts.maxDepth: limit tree depth (e.g., 5)
-                      opts.interactableOnly: only show elements with refs
-                      opts.format: "yaml" (default) or "compact"
+                      opts.interactableOnly: only clickable/input elements
   ref(id)           - Get element by ref ID (chainable - supports all ElementHandle methods)
                       Example: await ref('e1').click()
                       Example: await ref('e1').getAttribute('data-foo')
+  ref(id).source()  - Get React component source file info for element
+                      Returns { filePath, lineNumber, componentName } or null
+  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: get the nth matching element (0-indexed)
+                      Example: await component('Button', {nth: 0})
   fill(id, text)    - Clear and fill input (works with rich text editors)
   drag(opts)        - Drag with custom MIME types
                       opts.from: source selector or ref ID (e.g., "e1" or "text=src")
@@ -17888,21 +18123,16 @@ HELPERS
                       await waitFor('.btn')         - wait for selector
                       await waitFor('networkidle')  - wait for network idle
                       await waitFor('load')         - wait for page load
-  ref(id).source()  - Get React component source file info for element
-                      Returns { filePath, lineNumber, componentName } or null
   grab              - React Grab client API (activate, copyElement, etc)
 
-SNAPSHOT FORMATS
+SNAPSHOT OPTIONS
   # Full YAML tree (default, can be large)
   execute "return await snapshot()"
 
   # Interactable only (recommended - much smaller!)
   execute "return await snapshot({interactableOnly: true})"
 
-  # Compact format (minimal output: ref:role:name|ref:role:name)
-  execute "return await snapshot({format: 'compact'})"
-
-  # Combined options
+  # With depth limit
   execute "return await snapshot({interactableOnly: true, maxDepth: 6})"
 
 SCREENSHOTS - PREFER ELEMENT OVER FULL PAGE
@@ -17946,15 +18176,28 @@ COMMON PATTERNS
     dataTransfer: { 'application/x-custom': 'data' }
   })"
 
-  # Get React component source file
-  execute "return await ref('e1').source()"
-
   # Get page info
   execute "return {url: page.url(), title: await page.title()}"
 
   # CSS selector fallback (refs are now in DOM as aria-ref)
   execute "await page.click('[aria-ref="e1"]')"
 
+REACT-SPECIFIC PATTERNS
+  # Get React component source file
+  execute "return await ref('e1').source()"
+
+  # Get component props
+  execute "return await ref('e1').props()"
+
+  # Get component state
+  execute "return await ref('e1').state()"
+
+  # Find elements by React component name
+  execute "const buttons = await component('Button'); return buttons.length"
+
+  # Get the first Button component and click it
+  execute "const btn = await component('Button', {nth: 0}); await btn.click()"
+
 MULTI-PAGE SESSIONS
   execute "await page.goto('https://github.com')" --page github
   execute "return await snapshot({interactableOnly: true})" --page github
@@ -18011,14 +18254,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";
+var VERSION3 = "0.1.0-beta.4";
 var isMac = process.platform === "darwin";
 var META_LABEL = isMac ? "Cmd" : "Win";
 var ALT_LABEL = isMac ? "Option" : "Alt";
@@ -18505,7 +18741,7 @@ var uninstallPackagesWithFeedback = (packages, packageManager, projectRoot) => {
     handleError(error48);
   }
 };
-var VERSION4 = "0.1.0";
+var VERSION4 = "0.1.0-beta.4";
 var REPORT_URL = "https://react-grab.com/api/report-cli";
 var DOCS_URL = "https://github.com/aidenybai/react-grab";
 var promptAgentIntegration = async (cwd, customPkg) => {
@@ -18549,19 +18785,29 @@ var promptAgentIntegration = async (cwd, customPkg) => {
     }
   }
   if (integrationType === "skill" || integrationType === "both") {
-    logger.break();
-    const skillSpinner = spinner("Installing browser automation skill").start();
-    try {
-      child_process.execSync(`npx -y openskills install aidenybai/react-grab -y`, {
-        stdio: "inherit",
-        cwd
-      });
-      logger.break();
-      skillSpinner.succeed("Skill installed to .claude/skills/");
-    } catch {
+    const { skillTarget } = await prompts3__default.default({
+      type: "select",
+      name: "skillTarget",
+      message: `Which ${highlighter.info("agent")} would you like to install the skill for?`,
+      choices: SUPPORTED_TARGETS.map((target) => ({
+        title: target,
+        value: target
+      }))
+    });
+    if (skillTarget) {
       logger.break();
-      skillSpinner.fail("Failed to install skill");
-      logger.dim("Try manually: npx -y openskills install aidenybai/react-grab");
+      const skillSpinner = spinner("Installing browser automation skill").start();
+      try {
+        const skill = await fetchSkillFile();
+        const skillDir = path.join(cwd, AGENT_TARGETS[skillTarget]);
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(path.join(skillDir, "SKILL.md"), skill);
+        skillSpinner.succeed(`Skill installed to ${AGENT_TARGETS[skillTarget]}/`);
+      } catch {
+        skillSpinner.fail("Failed to install skill");
+        logger.dim("Try manually: npx -y openskills install aidenybai/react-grab");
+      }
     }
   }
   logger.break();
@@ -19197,7 +19443,7 @@ var init = new commander.Command().name("init").description("initialize React Gr
     await reportToCli("error", void 0, error48);
   }
 });
-var VERSION5 = "0.1.0";
+var VERSION5 = "0.1.0-beta.4";
 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 +19622,7 @@ var remove = new commander.Command().name("remove").description("remove an agent
 });
 
 // src/cli.ts
-var VERSION6 = "0.1.0";
+var VERSION6 = "0.1.0-beta.4";
 var VERSION_API_URL = "https://www.react-grab.com/api/version";
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));