gravity-core 1.0.2 → 1.0.3

package/README.md

@@ -14,7 +14,7 @@ Gravity will:
 3. Analyze its position, styles, and visibility
 4. Return specific issues and fixes
 
-## 🚀 Quick Start (3 minutes)
+## 🚀 Quick Start (5 minutes)
 
 ### 1. Install Package
 
@@ -22,29 +22,48 @@ Gravity will:
 npm install gravity-core
 ```
 
-### 2. Extract Chrome Extension
+### 2. Setup Extension
 
 ```bash
-npx gravity-core setup-extension
+gravity setup-extension
 ```
 
-This creates a `gravity-extension/` folder in your current directory with all the extension files.
+This extracts the Chrome extension to `~/.gravity-extension`.
 
-### 3. Load Extension in Chrome
+### 3. Setup Native Host
+
+```bash
+gravity setup-native-host
+```
+
+This:
+- Auto-detects your Gravity extension ID
+- Asks for confirmation before modifying registry
+- Sets up native messaging for Chrome
+- Optionally restarts Chrome
+
+### 4. Load Extension in Chrome
 
 1. Open Chrome and go to `chrome://extensions`
 2. Enable "Developer mode" (toggle in top right)
 3. Click "Load unpacked"
-4. Select the `gravity-extension/` folder that was just created
+4. Select the `~/.gravity-extension` folder
 5. ✅ Done!
 
-### 4. Connect to Tab
+### 5. Test Connection
 
-1. Click the Gravity extension icon in your toolbar
-2. Click "Connect to Tab"
-3. Status turns 🟢 Green
+```bash
+gravity test-connection
+```
 
-### 5. Configure Your IDE
+This verifies:
+- ✅ Registry key exists
+- ✅ Manifest is valid
+- ✅ Extension ID is configured
+- ✅ Native host is executable
+- ✅ WebSocket connection works
+
+### 6. Configure Your IDE
 
 **VSCode:**
 ```json
@@ -78,7 +97,7 @@ Same as VSCode
 **Warp or any IDE with MCP:**
 Add the same config to your IDE's MCP settings.
 
-### 6. Start Diagnosing
+### 7. Start Diagnosing
 
 Ask your AI:
 - "Diagnose the #modal element"
@@ -119,7 +138,7 @@ Your IDE (VSCode, Cursor, Kiro, etc.)
     ↓
 MCP Server (gravity-core)
     ↓
-WebSocket Connection (port 9224)
+Native Messaging Host (Windows Registry)
     ↓
 Chrome Extension (running native bridge)
     ↓
@@ -141,9 +160,9 @@ Browser Tab (DOM, CSS, Layout data)
 
 ### Fix Offscreen Modal
 
-1. Browser: Open page with broken layout
-2. Terminal: Run `npx gravity-core setup-extension`
-3. Chrome: Load the extension from `gravity-extension/` folder
+1. Terminal: Run `gravity setup-extension` and `gravity setup-native-host`
+2. Chrome: Load extension from `~/.gravity-extension`
+3. Browser: Open page with broken layout
 4. Extension: Click icon → "Connect to Tab" (🟢 Green)
 5. IDE: Ask AI: "Diagnose the .modal element"
 6. AI: Shows "Element extends 50px beyond right edge"
@@ -164,26 +183,58 @@ Browser Tab (DOM, CSS, Layout data)
 
 ### Setup Extension
 
-Extract the Chrome extension to your current directory:
+Extract the Chrome extension to your home directory:
+
+```bash
+gravity setup-extension
+```
+
+Creates `~/.gravity-extension/` ready to load in Chrome.
+
+### Setup Native Host
+
+Configure native messaging for Chrome:
+
+```bash
+gravity setup-native-host
+```
+
+This command:
+- Auto-detects your Gravity extension ID
+- Asks for confirmation before modifying registry
+- Copies native host to `~/.gravity-host/`
+- Patches manifest with extension ID
+- Writes Windows registry entry
+- Optionally restarts Chrome
+
+### Test Connection
+
+Verify everything is working:
 
 ```bash
-npx gravity-core setup-extension
+gravity test-connection
 ```
 
-Creates a `gravity-extension/` folder ready to load in Chrome.
+Checks:
+- Registry key exists
+- Manifest file is valid
+- Extension ID is configured
+- Native host is executable
+- WebSocket connection works
+- Browser handshake succeeds
 
 ### Start MCP Server
 
 Run the MCP server (used by your IDE):
 
 ```bash
-npx gravity-core
+gravity
 ```
 
 ### Show Help
 
 ```bash
-npx gravity-core --help
+gravity --help
 ```
 
 ## 🔧 API Reference
@@ -251,28 +302,44 @@ bridge.on('error', (error) => {
 
 ## 🐛 Troubleshooting
 
-**"Not connected to browser"**
-- Make sure Chrome/Edge is open
-- Click extension icon → "Connect to Tab"
-- Status should turn green
+### "Could not find Gravity extension"
 
-**"Extension not loaded"**
-- Run `npx gravity-core setup-extension`
-- Go to `chrome://extensions`
-- Enable "Developer mode"
-- Click "Load unpacked"
-- Select the `gravity-extension/` folder
+**Solution:**
+1. Run `gravity setup-extension`
+2. Open Chrome and go to `chrome://extensions`
+3. Enable "Developer mode"
+4. Click "Load unpacked"
+5. Select `~/.gravity-extension`
+6. Run `gravity setup-native-host`
 
-**"Port 9224 already in use"**
-- Edit extension's `background.js` in the `gravity-extension/` folder
-- Change `WEBSOCKET_PORT` to 9225
-- Update IDE config with `GRAVITY_PORT: 9225`
+### "Registry key not found"
 
-**"Element not found"**
+**Solution:**
+- Run `gravity setup-native-host` again
+- You may need to run as Administrator
+- Check that Chrome is installed in the default location
+
+### "WebSocket connection failed"
+
+**Solution:**
+- Make sure the MCP server is running: `gravity`
+- Check that port 9224 is not blocked by firewall
+- Try a different port: `GRAVITY_PORT=9225 gravity`
+
+### "Element not found"
+
+**Solution:**
 - Check selector is correct
 - Make sure element exists in page
 - Try simpler selector: `div` instead of `#modal`
 
+### "Chrome is running" warning
+
+**Solution:**
+- The setup will ask if you want to restart Chrome
+- Restart Chrome manually if you prefer
+- Changes take effect after restart
+
 ## 📖 Documentation
 
 - [Setup Guide](./SETUP.md) - Complete setup instructions
@@ -293,6 +360,8 @@ bridge.on('error', (error) => {
 - ✅ No external API calls
 - ✅ All data stays local
 - ✅ No user data collection
+- ✅ Registry changes require explicit user confirmation
+- ✅ No silent installations or modifications
 
 ## 📝 License
 
@@ -313,7 +382,9 @@ Contributions welcome! Please open an issue or PR on GitHub.
 
 ```bash
 npm install gravity-core
-npx gravity-core setup-extension
+gravity setup-extension
+gravity setup-native-host
+gravity test-connection
 ```
 
-Then load the extension in Chrome and configure your IDE. Happy debugging! 🎉
+Then configure your IDE and start debugging! 🎉