@react-grab/droid 0.0.89

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 (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +156 -0
  3. package/package.json +43 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Aiden Bai
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,156 @@
1
+ # @react-grab/droid
2
+
3
+ Factory Droid provider for React Grab. Requires running a local server that interfaces with the Factory CLI (`droid exec`).
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @react-grab/droid
9
+ # or
10
+ pnpm add @react-grab/droid
11
+ # or
12
+ bun add @react-grab/droid
13
+ # or
14
+ yarn add @react-grab/droid
15
+ ```
16
+
17
+ ## Prerequisites
18
+
19
+ You must have the Factory CLI installed:
20
+
21
+ ```bash
22
+ curl -fsSL https://app.factory.ai/cli | sh
23
+ ```
24
+
25
+ And set your Factory API key:
26
+
27
+ ```bash
28
+ export FACTORY_API_KEY=fk-...
29
+ ```
30
+
31
+ ## Server Setup
32
+
33
+ The server runs on port `10567` by default.
34
+
35
+ ### Quick Start (CLI)
36
+
37
+ Start the server in the background before running your dev server:
38
+
39
+ ```bash
40
+ npx @react-grab/droid@latest && pnpm run dev
41
+ ```
42
+
43
+ The server will run as a detached background process. **Note:** Stopping your dev server (Ctrl+C) won't stop the React Grab server. To stop it:
44
+
45
+ ```bash
46
+ pkill -f "react-grab.*server"
47
+ ```
48
+
49
+ ### Recommended: Config File (Automatic Lifecycle)
50
+
51
+ For better lifecycle management, start the server from your config file. This ensures the server stops when your dev server stops:
52
+
53
+ ### Vite
54
+
55
+ ```ts
56
+ // vite.config.ts
57
+ import { startServer } from "@react-grab/droid/server";
58
+
59
+ if (process.env.NODE_ENV === "development") {
60
+ startServer();
61
+ }
62
+ ```
63
+
64
+ ### Next.js
65
+
66
+ ```ts
67
+ // next.config.ts
68
+ import { startServer } from "@react-grab/droid/server";
69
+
70
+ if (process.env.NODE_ENV === "development") {
71
+ startServer();
72
+ }
73
+ ```
74
+
75
+ ## Client Usage
76
+
77
+ ### Script Tag
78
+
79
+ ```html
80
+ <script src="//unpkg.com/react-grab/dist/index.global.js"></script>
81
+ <script src="//unpkg.com/@react-grab/droid/dist/client.global.js"></script>
82
+ ```
83
+
84
+ ### Next.js
85
+
86
+ Using the `Script` component in your `app/layout.tsx`:
87
+
88
+ ```jsx
89
+ import Script from "next/script";
90
+
91
+ export default function RootLayout({ children }) {
92
+ return (
93
+ <html>
94
+ <head>
95
+ {process.env.NODE_ENV === "development" && (
96
+ <>
97
+ <Script
98
+ src="//unpkg.com/react-grab/dist/index.global.js"
99
+ strategy="beforeInteractive"
100
+ />
101
+ <Script
102
+ src="//unpkg.com/@react-grab/droid/dist/client.global.js"
103
+ strategy="lazyOnload"
104
+ />
105
+ </>
106
+ )}
107
+ </head>
108
+ <body>{children}</body>
109
+ </html>
110
+ );
111
+ }
112
+ ```
113
+
114
+ ### ES Module
115
+
116
+ ```tsx
117
+ import { attachAgent } from "@react-grab/droid/client";
118
+
119
+ attachAgent();
120
+ ```
121
+
122
+ ## Configuration Options
123
+
124
+ The provider supports the following options:
125
+
126
+ ```typescript
127
+ interface DroidAgentOptions {
128
+ autoLevel?: "low" | "medium" | "high"; // Autonomy level (default: "low")
129
+ model?: string; // Model to use (e.g., "claude-sonnet-4-5-20250929")
130
+ reasoningEffort?: "low" | "medium" | "high";
131
+ workspace?: string; // Working directory
132
+ }
133
+ ```
134
+
135
+ ## How It Works
136
+
137
+ ```
138
+ ┌─────────────────┐ HTTP ┌─────────────────┐ stdin ┌─────────────────┐
139
+ │ │ localhost:10567 │ │ │ │
140
+ │ React Grab │ ──────────────► │ Server │ ─────────────► │ droid exec │
141
+ │ (Browser) │ ◄────────────── │ (Node.js) │ ◄───────────── │ (CLI) │
142
+ │ │ SSE │ │ stdout │ │
143
+ └─────────────────┘ └─────────────────┘ └─────────────────┘
144
+ Client Server Agent
145
+ ```
146
+
147
+ 1. **React Grab** sends the selected element context to the server via HTTP POST
148
+ 2. **Server** receives the request and spawns `droid exec` with `--output-format stream-json`
149
+ 3. **droid exec** processes the request and streams JSON responses to stdout
150
+ 4. **Server** relays status updates to the client via Server-Sent Events (SSE)
151
+
152
+ ## Autonomy Levels
153
+
154
+ - `low` (default): File edits only, no system modifications
155
+ - `medium`: Includes package installations, local git operations
156
+ - `high`: Full access including git push, deployments
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@react-grab/droid",
3
+ "version": "0.0.89",
4
+ "type": "module",
5
+ "bin": {
6
+ "react-grab-droid": "./dist/cli.cjs"
7
+ },
8
+ "exports": {
9
+ "./client": {
10
+ "types": "./dist/client.d.ts",
11
+ "import": "./dist/client.js",
12
+ "require": "./dist/client.cjs"
13
+ },
14
+ "./server": {
15
+ "types": "./dist/server.d.ts",
16
+ "import": "./dist/server.js",
17
+ "require": "./dist/server.cjs"
18
+ },
19
+ "./dist/*": "./dist/*.js",
20
+ "./dist/*.js": "./dist/*.js"
21
+ },
22
+ "browser": "dist/client.global.js",
23
+ "files": [
24
+ "dist"
25
+ ],
26
+ "devDependencies": {
27
+ "@types/node": "^22.10.7",
28
+ "tsup": "^8.4.0",
29
+ "@react-grab/utils": "0.0.89"
30
+ },
31
+ "dependencies": {
32
+ "@hono/node-server": "^1.19.6",
33
+ "execa": "^9.6.0",
34
+ "fkill": "^9.0.0",
35
+ "hono": "^4.0.0",
36
+ "picocolors": "^1.1.1",
37
+ "react-grab": "0.0.89"
38
+ },
39
+ "scripts": {
40
+ "dev": "tsup --watch",
41
+ "build": "rm -rf dist && NODE_ENV=production tsup"
42
+ }
43
+ }