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

grab 0.0.97 → 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 +132 -372
package/dist/chunk-DIAOCH5J.cjs +88 -0
package/dist/chunk-VXZ5VMRT.js +88 -0
package/dist/cli.cjs +1 -420
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-RhgdSH9U.d.cts → index-BdKhAk4Q.d.cts} +106 -31
package/dist/{index-RhgdSH9U.d.ts → index-BdKhAk4Q.d.ts} +106 -31
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 +27 -35
package/dist/index.js +2 -2
package/dist/styles.css +1 -1
package/package.json +1 -1
package/dist/chunk-K6AYIDZE.js +0 -94
package/dist/chunk-QVFHXAET.cjs +0 -94

package/README.md CHANGED Viewed

@@ -6,20 +6,36 @@
 Select context for coding agents directly from your website
-How? Point at any element and it'll send the file name, React component, and HTML source code.
+How? Point at any element and press **⌘C** (Mac) or **Ctrl+C** (Windows/Linux) to copy the file name, React component, and HTML source code.
 It makes tools like Cursor, Claude Code, Copilot run up to [**3× faster**](https://react-grab.com/blog/intro) and more accurate.
 ### [Try out a demo! →](https://react-grab.com)
-https://github.com/user-attachments/assets/fdb34329-b471-4b39-b433-0b1a27a94bd8
+![React Grab Demo](https://github.com/aidenybai/react-grab/blob/main/packages/website/public/demo.gif?raw=true)
 ## Install
 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
+Once installed, hover over any UI element in your browser and press:
+- **⌘C** (Cmd+C) on Mac
+- **Ctrl+C** on Windows/Linux
+This copies the element's context (file name, React component, and HTML source code) to your clipboard ready to paste into your coding agent. For example:
+```js
+<a class="ml-auto inline-block text-sm" href="#">
+  Forgot your password?
+</a>
+in LoginForm at components/login-form.tsx:46:19
 ```
 ## Manual Installation
@@ -120,428 +136,172 @@ if (process.env.NODE_ENV === "development") {
 }
 ```
-## Coding agent integration
-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.
-This means **no copying and pasting** - just select the element and let the agent do the rest. [Learn more →](https://react-grab.com/blog/agent)
-<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
+## MCP Server
-```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"
-  }
-}
-```
+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.
-> **Note:** You must have [Codex](https://github.com/openai/codex) installed (`npm i -g @openai/codex`).
+### Setup
-#### Client Setup
+Run during project init:
-```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>
+Supported clients: `cursor`, `claude-code`, `vscode`, `opencode`, `codex`, `gemini-cli`, `windsurf`, `zed`, `droid`
-<details>
-<summary><strong>Gemini</strong></summary>
-#### 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>
+#### Lifecycle Hooks Plugin
-<details>
-<summary><strong>Factory Droid</strong></summary>
+Track element selections with analytics:
-#### Server Setup
-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`:
-```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