refactor: enhance plugin registration and API options handling (#102)

* refactor: enhance plugin registration and API options handling

- Updated the API to include a `registerPlugin` method, allowing for more flexible plugin management.
- Refactored existing code to utilize the new plugin system, improving extensibility and maintainability.
- Adjusted type definitions and interfaces to support the new plugin architecture, ensuring compatibility with existing functionality.

* docs: update README for plugin system enhancements and usage examples

- Revised sections on plugin registration and lifecycle hooks to reflect recent API changes.
- Added detailed examples for new plugins, including analytics and context menu actions.
- Improved clarity in usage instructions and added a section on unregistering plugins.

* fix

* Update packages/grab/README.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* Update README.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* feat: enhance file opening functionality with plugin hooks

- Added `onOpenFile` hook to allow plugins to handle file opening events, providing flexibility for custom behaviors.
- Updated context menu handling to utilize the new `onOpenFile` hook, improving integration with plugins.
- Refactored related code to ensure consistent handling of file opening across the application.

* refactor: streamline agent capabilities handling in core index

- Updated the logic for setting agent capabilities to use a captured provider, improving clarity and reducing redundancy.
- Enhanced connection checking for the agent provider, ensuring accurate updates to the agent's connection status.
- Refactored related code for better maintainability and consistency in handling agent options.

* fix

* refactor: update plugin contribution interface and related types

- Renamed `PluginContribution` to `PluginConfig` to better reflect its purpose.
- Adjusted type definitions in the core and types files to ensure consistency with the new naming convention.
- Updated imports and references throughout the codebase to align with the refactored interface.

* refactor: improve options handling in plugin registry

- Enhanced the `setOptions` function to streamline the updating of plugin options, ensuring undefined values are ignored.
- Updated the logic for merging options to include direct overrides, improving the clarity and maintainability of the code.
- Refactored related code to ensure consistent handling of options within the plugin registry.

---------

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

Author: aidenybai

README.md

@@ -529,37 +529,98 @@ export default function RootLayout({ children }) {
 
 ## Extending React Grab
 
-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.
+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.
+
+#### Basic Usage
 
 ```typescript
 import { init } from "react-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
+const api = init();
+
+api.activate();
+api.copyElement(document.querySelector(".my-element"));
+console.log(api.getState());
+```
+
+#### Lifecycle Hooks Plugin
+
+Track element selections with analytics:
+
+```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 });
     },
-    elementLabel: {
-      enabled: false, // disable element label
+    onCopySuccess: (elements, content) => {
+      analytics.track("copy", { count: elements.length });
     },
   },
+});
+```
 
-  onElementSelect: (element) => {
-    console.log("Selected:", element);
-  },
-  onCopySuccess: (elements, content) => {
-    console.log("Copied to clipboard:", content);
-  },
-  onStateChange: (state) => {
-    console.log("Active:", state.isActive);
+#### Context Menu Plugin
+
+Add custom actions to the right-click menu:
+
+```typescript
+api.registerPlugin({
+  name: "custom-actions",
+  contextMenuActions: [
+    {
+      label: "Log to Console",
+      handler: ({ elements }) => console.dir(elements[0]),
+    },
+  ],
+});
+```
+
+#### Theme Plugin
+
+Customize the UI appearance:
+
+```typescript
+api.registerPlugin({
+  name: "theme",
+  theme: {
+    hue: 180, // shift colors (pink → cyan)
+    crosshair: { enabled: false },
+    elementLabel: { enabled: false },
   },
 });
+```
 
-api.activate();
-api.copyElement(document.querySelector(".my-element"));
-console.log(api.getState());
+#### Agent Plugin
+
+Create a custom agent that processes selected elements:
+
+```typescript
+api.registerPlugin({
+  name: "my-custom-agent",
+  agent: {
+    provider: {
+      async *send({ prompt, elements, content }) {
+        yield "Analyzing element...";
+
+        const response = await fetch("/api/ai", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ prompt, content }),
+        });
+
+        yield "Processing response...";
+
+        const result = await response.json();
+        yield `Done: ${result.message}`;
+      },
+    },
+  },
+});
 ```
 
 ## Resources & Contributing Back

packages/grab/README.md

@@ -529,37 +529,98 @@ export default function RootLayout({ children }) {
 
 ## Extending React Grab
 
-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.
+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.
+
+#### Basic Usage
 
 ```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
+const api = init();
+
+api.activate();
+api.copyElement(document.querySelector(".my-element"));
+console.log(api.getState());
+```
+
+#### Lifecycle Hooks Plugin
+
+Track element selections with analytics:
+
+```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 });
     },
-    elementLabel: {
-      enabled: false, // disable element label
+    onCopySuccess: (elements, content) => {
+      analytics.track("copy", { count: elements.length });
     },
   },
+});
+```
 
-  onElementSelect: (element) => {
-    console.log("Selected:", element);
-  },
-  onCopySuccess: (elements, content) => {
-    console.log("Copied to clipboard:", content);
-  },
-  onStateChange: (state) => {
-    console.log("Active:", state.isActive);
+#### Context Menu Plugin
+
+Add custom actions to the right-click menu:
+
+```typescript
+api.registerPlugin({
+  name: "custom-actions",
+  contextMenuActions: [
+    {
+      label: "Log to Console",
+      handler: ({ elements }) => console.dir(elements[0]),
+    },
+  ],
+});
+```
+
+#### Theme Plugin
+
+Customize the UI appearance:
+
+```typescript
+api.registerPlugin({
+  name: "theme",
+  theme: {
+    hue: 180, // shift colors (pink → cyan)
+    crosshair: { enabled: false },
+    elementLabel: { enabled: false },
   },
 });
+```
 
-api.activate();
-api.copyElement(document.querySelector(".my-element"));
-console.log(api.getState());
+#### Agent Plugin
+
+Create a custom agent that processes selected elements:
+
+```typescript
+api.registerPlugin({
+  name: "my-custom-agent",
+  agent: {
+    provider: {
+      async *send({ prompt, elements, content }) {
+        yield "Analyzing element...";
+
+        const response = await fetch("/api/ai", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ prompt, content }),
+        });
+
+        yield "Processing response...";
+
+        const result = await response.json();
+        yield `Done: ${result.message}`;
+      },
+    },
+  },
+});
 ```
 
 ## Resources & Contributing Back

packages/provider-ami/src/client.ts

@@ -250,7 +250,7 @@ const runAgent = async (
 };
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 interface SessionData {
   messages: AmiUIMessage[];
@@ -550,7 +550,10 @@ export const attachAgent = async () => {
   const provider = createAmiAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "ami-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;

packages/provider-amp/src/client.ts

@@ -29,7 +29,7 @@ interface AmpAgentProviderOptions {
 }
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 export const createAmpAgentProvider = (
   providerOptions: AmpAgentProviderOptions = {},
@@ -115,7 +115,10 @@ export const attachAgent = async () => {
   const provider = createAmpAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "amp-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;

packages/provider-claude-code/src/client.ts

@@ -39,7 +39,7 @@ interface ClaudeAgentProviderOptions {
 }
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 export const createClaudeAgentProvider = (
   providerOptions: ClaudeAgentProviderOptions = {},
@@ -120,7 +120,10 @@ export const attachAgent = async () => {
   const provider = createClaudeAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "claude-code-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;

packages/provider-codex/src/client.ts

@@ -30,7 +30,7 @@ interface CodexAgentProviderOptions {
 }
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 export const createCodexAgentProvider = (
   options: CodexAgentProviderOptions = {},
@@ -112,7 +112,10 @@ export const attachAgent = async () => {
   const provider = createCodexAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "codex-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;

packages/provider-cursor/src/client.ts

@@ -31,7 +31,7 @@ interface CursorAgentProviderOptions {
 }
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 export const createCursorAgentProvider = (
   providerOptions: CursorAgentProviderOptions = {},
@@ -119,7 +119,10 @@ export const attachAgent = async () => {
   const provider = createCursorAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "cursor-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;

packages/provider-droid/src/client.ts

@@ -36,7 +36,7 @@ interface DroidAgentProviderOptions {
 }
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 export const createDroidAgentProvider = (
   providerOptions: DroidAgentProviderOptions = {},
@@ -119,7 +119,10 @@ export const attachAgent = async () => {
   const provider = createDroidAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "droid-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;

packages/provider-gemini/src/client.ts

@@ -30,7 +30,7 @@ interface GeminiAgentProviderOptions {
 }
 
 const isReactGrabApi = (value: unknown): value is ReactGrabAPI =>
-  typeof value === "object" && value !== null && "setOptions" in value;
+  typeof value === "object" && value !== null && "registerPlugin" in value;
 
 export const createGeminiAgentProvider = (
   providerOptions: GeminiAgentProviderOptions = {},
@@ -118,7 +118,10 @@ export const attachAgent = async () => {
   const provider = createGeminiAgentProvider();
 
   const attach = (api: ReactGrabAPI) => {
-    api.setOptions({ agent: { provider, storage: sessionStorage } });
+    api.registerPlugin({
+      name: "gemini-agent",
+      agent: { provider, storage: sessionStorage },
+    });
   };
 
   const existingApi = window.__REACT_GRAB__;