npm - grab - Versions diffs - 0.0.98 → 0.1.0-beta.0 - Mend

grab 0.0.98 → 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +114 -372
package/dist/chunk-DIAOCH5J.cjs +88 -0
package/dist/chunk-VXZ5VMRT.js +88 -0
package/dist/cli.cjs +1 -1137
package/dist/core/index.cjs +1 -1
package/dist/core/index.d.cts +1 -1
package/dist/core/index.d.ts +1 -1
package/dist/core/index.js +1 -1
package/dist/{index-r1odQUH0.d.cts → index-BdKhAk4Q.d.cts} +79 -28
package/dist/{index-r1odQUH0.d.ts → index-BdKhAk4Q.d.ts} +79 -28
package/dist/index.cjs +2 -2
package/dist/index.d.cts +15 -3
package/dist/index.d.ts +15 -3
package/dist/index.global.js +25 -25
package/dist/index.js +2 -2
package/dist/styles.css +1 -1
package/package.json +1 -1
package/dist/chunk-D2FWI6AP.js +0 -88
package/dist/chunk-H4U7EPBM.cjs +0 -88

package/README.md CHANGED Viewed

@@ -19,7 +19,7 @@ It makes tools like Cursor, Claude Code, Copilot run up to [**3× faster**](http
 Run this command to install React Grab into your project. Ensure you are running at project root (e.g. where the `next.config.ts` or `vite.config.ts` file is located).
 ```html
-npx grab@latest init
+npx -y grab@latest init
 ```
 ## Usage
@@ -136,430 +136,172 @@ if (process.env.NODE_ENV === "development") {
 }
 ```
-## Coding agent integration
+## MCP Server
-React Grab can send selected element context directly to your coding agent. This enables a workflow where you select a UI element and an agent automatically makes changes to your codebase.
+React Grab includes an MCP (Model Context Protocol) server that gives AI coding agents direct access to your browser. This enables agents to navigate, click, fill forms, and take screenshots.
-This means **no copying and pasting** - just select the element and let the agent do the rest. [Read more about coding agent integration →](https://react-grab.com/blog/agent)
+### Setup
-> **Click to expand** setup instructions for your coding agent:
+Run during project init:
-<details>
-<summary><strong>Claude Code</strong></summary>
-#### Server Setup
-The server runs on port `4567` and interfaces with the Claude Agent SDK. Add to your `package.json`:
-```json
-{
-  "scripts": {
-    "dev": "npx @react-grab/claude-code@latest && next dev"
-  }
-}
-```
-#### Client Setup
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/claude-code/dist/client.global.js"></script>
-```
-Or using Next.js `Script` component in your `app/layout.tsx`:
-```jsx
-import Script from "next/script";
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/claude-code/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-</details>
-<details>
-<summary><strong>Cursor CLI</strong></summary>
-You must have the [`cursor-agent` CLI](https://cursor.com/docs/cli/overview) installed.
-#### Server Setup
-The server runs on port `5567` and interfaces with the `cursor-agent` CLI. Add to your `package.json`:
-```json
-{
-  "scripts": {
-    "dev": "npx @react-grab/cursor@latest && next dev"
-  }
-}
-```
-#### Client Setup
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/cursor/dist/client.global.js"></script>
-```
-Or using Next.js `Script` component in your `app/layout.tsx`:
-```jsx
-import Script from "next/script";
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/cursor/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-</details>
-<details>
-<summary><strong>OpenCode</strong></summary>
-#### Server Setup
-The server runs on port `6567` and interfaces with the OpenCode CLI. Add to your `package.json`:
-```json
-{
-  "scripts": {
-    "dev": "npx @react-grab/opencode@latest && next dev"
-  }
-}
-```
-> **Note:** You must have [OpenCode](https://opencode.ai) installed (`npm i -g opencode-ai@latest`).
-#### Client Setup
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/opencode/dist/client.global.js"></script>
-```
-Or using Next.js `Script` component in your `app/layout.tsx`:
-```jsx
-import Script from "next/script";
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/opencode/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-</details>
-<details>
-<summary><strong>Codex</strong></summary>
-#### Server Setup
-The server runs on port `7567` and interfaces with the OpenAI Codex SDK. Add to your `package.json`:
-```json
-{
-  "scripts": {
-    "dev": "npx @react-grab/codex@latest && next dev"
-  }
-}
-```
-> **Note:** You must have [Codex](https://github.com/openai/codex) installed (`npm i -g @openai/codex`).
-#### Client Setup
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/codex/dist/client.global.js"></script>
+```bash
+npx -y grab@latest init
+# When prompted, choose to add the MCP server
 ```
-Or using Next.js `Script` component in your `app/layout.tsx`:
+Or add it separately:
-```jsx
-import Script from "next/script";
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/codex/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
+```bash
+npx -y grab@latest add mcp --client cursor
 ```
-</details>
-<details>
-<summary><strong>Gemini</strong></summary>
+Supported clients: `cursor`, `claude-code`, `vscode`, `opencode`, `codex`, `gemini-cli`, `windsurf`, `zed`, `droid`
-#### Server Setup
-The server runs on port `8567` and interfaces with the Gemini CLI. Add to your `package.json`:
+Or add it manually to your `mcp.json` file:
 ```json
 {
-  "scripts": {
-    "dev": "npx @react-grab/gemini@latest && next dev"
+  "mcpServers": {
+    "react-grab-browser": {
+      "command": "npx",
+      "args": ["-y", "@react-grab/cli", "browser", "mcp"]
+    }
   }
 }
 ```
-> **Note:** You must have [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed.
+### MCP Tools
-#### Client Setup
+Once configured, your agent has access to:
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/gemini/dist/client.global.js"></script>
-```
+- `browser_snapshot` - Get ARIA accessibility tree with element refs (e1, e2...)
+- `browser_execute` - Run Playwright code with helpers like `ref('e1').click()`
-Or using Next.js `Script` component in your `app/layout.tsx`:
+## Skill
-```jsx
-import Script from "next/script";
+For agents that support skills (like Codex), install the `react-grab-browser` skill:
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/gemini/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
+```bash
+npx -y grab@latest add skill
+# or
+npx -y openskills install aidenybai/react-grab -y
 ```
-</details>
+The skill provides browser automation with Playwright using your real browser cookies. See the [skill documentation](https://github.com/aidenybai/react-grab/blob/main/skills/react-grab-browser/SKILL.md) for full details.
-<details>
-<summary><strong>Amp</strong></summary>
+## Claude Plugin
-#### Server Setup
+React Grab includes a Claude plugin for Claude Code/Desktop. The plugin is located in `.claude-plugin/` and provides browser automation capabilities.
-The server runs on port `9567` and interfaces with the [Amp SDK](https://ampcode.com/manual/sdk). Add to your `package.json`:
+To use it, ensure the plugin files are present:
+- `.claude-plugin/marketplace.json` - Plugin manifest
+- `.claude/skills/react-grab-browser/` - Skill files (SKILL.md, EXAMPLES.md, REFERENCE.md)
-```json
-{
-  "scripts": {
-    "dev": "npx @react-grab/amp@latest && next dev"
-  }
-}
-```
+The plugin triggers on browser-related requests like "browse", "navigate to", "screenshot", "click on", "fill form", etc.
-> **Note:** You must have an [Amp API key](https://ampcode.com/settings) set via `AMP_API_KEY` environment variable.
+## Extending React Grab
-#### Client Setup
+React Grab uses a plugin system to extend functionality. Check out the [type definitions](https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/src/types.ts) to see all available options.
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/amp/dist/client.global.js"></script>
-```
+#### Basic Usage
-Or using Next.js `Script` component in your `app/layout.tsx`:
+```typescript
+import { init } from "grab/core";
-```jsx
-import Script from "next/script";
+const api = init();
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/amp/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
+api.activate();
+api.copyElement(document.querySelector(".my-element"));
+console.log(api.getState());
 ```
-</details>
-<details>
-<summary><strong>Factory Droid</strong></summary>
-#### Server Setup
+#### Lifecycle Hooks Plugin
-The server runs on port `10567` and interfaces with the [Factory CLI](https://docs.factory.ai/cli/droid-exec/overview). Add to your `package.json`:
+Track element selections with analytics:
-```json
-{
-  "scripts": {
-    "dev": "npx @react-grab/droid@latest && next dev"
-  }
-}
+```typescript
+api.registerPlugin({
+  name: "analytics",
+  hooks: {
+    onElementSelect: (element) => {
+      analytics.track("element_selected", { tagName: element.tagName });
+    },
+    onDragEnd: (elements, bounds) => {
+      analytics.track("drag_end", { count: elements.length, bounds });
+    },
+    onCopySuccess: (elements, content) => {
+      analytics.track("copy", { count: elements.length });
+    },
+  },
+});
 ```
-> **Note:** You must have [Factory CLI](https://app.factory.ai) installed (`curl -fsSL https://app.factory.ai/cli | sh`) and `FACTORY_API_KEY` environment variable set.
+#### Context Menu Plugin
-#### Client Setup
+Add custom actions to the right-click menu:
-```html
-<script src="//unpkg.com/grab/dist/index.global.js"></script>
-<!-- add this in the <head> -->
-<script src="//unpkg.com/@react-grab/droid/dist/client.global.js"></script>
+```typescript
+api.registerPlugin({
+  name: "custom-actions",
+  actions: [
+    {
+      id: "log-to-console",
+      label: "Log to Console",
+      onAction: ({ elements }) => console.dir(elements[0]),
+    },
+  ],
+});
 ```
-Or using Next.js `Script` component in your `app/layout.tsx`:
+#### Theme Plugin
-```jsx
-import Script from "next/script";
+Customize the UI appearance:
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <head>
-        {process.env.NODE_ENV === "development" && (
-          <>
-            <Script
-              src="//unpkg.com/grab/dist/index.global.js"
-              strategy="beforeInteractive"
-            />
-            <Script
-              src="//unpkg.com/@react-grab/droid/dist/client.global.js"
-              strategy="lazyOnload"
-            />
-          </>
-        )}
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}
+```typescript
+api.registerPlugin({
+  name: "theme",
+  theme: {
+    hue: 180, // shift colors (pink → cyan)
+    crosshair: { enabled: false },
+    elementLabel: { enabled: false },
+  },
+});
 ```
-</details>
-## Extending React Grab
+#### Agent Plugin
-React Grab provides an public customization API. Check out the [type definitions](https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/src/types.ts) to see all available options for extending React Grab.
+Create a custom agent that processes selected elements:
 ```typescript
-import { init } from "grab/core";
-const api = init({
-  theme: {
-    enabled: true, // disable all UI by setting to false
-    hue: 180, // shift colors by 180 degrees (pink → cyan/turquoise)
-    crosshair: {
-      enabled: false, // disable crosshair
-    },
-    elementLabel: {
-      enabled: false, // disable element label
+api.registerPlugin({
+  name: "my-custom-agent",
+  actions: [
+    {
+      id: "custom-agent",
+      label: "Ask AI",
+      onAction: ({ enterPromptMode }) => enterPromptMode?.(),
+      agent: {
+        provider: {
+          async *send({ prompt, content }, signal) {
+            yield "Analyzing element...";
+            const response = await fetch("/api/ai", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ prompt, content }),
+              signal,
+            });
+            yield "Processing response...";
+            const result = await response.json();
+            yield `Done: ${result.message}`;
+          },
+        },
+      },
     },
-  },
-  onElementSelect: (element) => {
-    console.log("Selected:", element);
-  },
-  onCopySuccess: (elements, content) => {
-    console.log("Copied to clipboard:", content);
-  },
-  onStateChange: (state) => {
-    console.log("Active:", state.isActive);
-  },
+  ],
 });
-api.activate();
-api.copyElement(document.querySelector(".my-element"));
-console.log(api.getState());
 ```
 ## Resources & Contributing Back