gravity-lite 3.0.0

package/extension/background.js

@@ -0,0 +1,197 @@
+// =============================================================================
+// Gravity v3 — Service Worker (MV3)
+//
+// Responsibilities:
+//   1. Manage chrome.debugger attachment (only works in SW context)
+//   2. Ensure the offscreen document (WebSocket bridge) is always alive
+//   3. Route messages between offscreen doc ↔ popup ↔ CDP
+//
+// The offscreen document owns the persistent WebSocket to the MCP server.
+// The SW wakes on demand to execute CDP commands via chrome.debugger.
+// =============================================================================
+
+let debuggerState = {
+  attached: false,
+  tabId: null,
+  domainsEnabled: false,
+  lastError: null,
+  attachmentTime: null,
+};
+
+let wsConnected = false; // reflects offscreen WS status
+
+// ── Offscreen document management ────────────────────────────────────────────
+
+async function ensureOffscreen() {
+  // chrome.offscreen available since Chrome 116
+  const existing = await chrome.offscreen.hasDocument().catch(() => false);
+  if (!existing) {
+    await chrome.offscreen.createDocument({
+      url: 'offscreen.html',
+      reasons: ['WORKERS'],
+      justification: 'Maintain persistent WebSocket connection to local MCP server bridge',
+    }).catch(() => {
+      // May fail if already being created — ignore
+    });
+  }
+}
+
+// ── Message routing ───────────────────────────────────────────────────────────
+
+chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+
+  // ── From offscreen document ───────────────────────────────────────────────
+  if (msg.to === 'sw') {
+
+    if (msg.type === 'ws_status') {
+      wsConnected = msg.connected;
+      // Broadcast to popup if open
+      chrome.runtime.sendMessage({ action: 'ws_status_update', connected: msg.connected }).catch(() => {});
+      return;
+    }
+
+    if (msg.type === 'cdp_request') {
+      // Execute CDP via chrome.debugger, send response back to offscreen
+      const { id, method, params } = msg.payload;
+
+      if (!debuggerState.attached || !debuggerState.tabId) {
+        chrome.runtime.sendMessage({
+          to: 'offscreen',
+          type: 'cdp_response',
+          payload: { type: 'cdp_response', id, error: { message: 'Debugger not attached. Click "Connect to Tab" in the Gravity popup.' } }
+        }).catch(() => {});
+        return;
+      }
+
+      chrome.debugger.sendCommand({ tabId: debuggerState.tabId }, method, params || {}, (result) => {
+        const response = chrome.runtime.lastError
+          ? { type: 'cdp_response', id, error: { message: chrome.runtime.lastError.message } }
+          : { type: 'cdp_response', id, result };
+
+        chrome.runtime.sendMessage({ to: 'offscreen', type: 'cdp_response', payload: response }).catch(() => {});
+      });
+      return;
+    }
+  }
+
+  // ── From popup ────────────────────────────────────────────────────────────
+
+  if (msg.action === 'attach') {
+    chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
+      if (!tabs?.[0]?.id) return sendResponse({ success: false, error: 'No active tab found' });
+      attachDebugger(tabs[0].id, sendResponse);
+    });
+    return true; // async
+  }
+
+  if (msg.action === 'detach') {
+    detachDebugger(sendResponse);
+    return true;
+  }
+
+  if (msg.action === 'status') {
+    sendResponse({ ...debuggerState, wsConnected });
+    return true;
+  }
+});
+
+// ── Debugger management ───────────────────────────────────────────────────────
+
+function attachDebugger(tabId, callback) {
+  debuggerState.lastError = null;
+
+  chrome.tabs.get(tabId, (tab) => {
+    if (chrome.runtime.lastError || !tab) {
+      const err = chrome.runtime.lastError?.message || 'Tab not found';
+      debuggerState.lastError = err;
+      return callback({ success: false, error: err });
+    }
+
+    if (tab.url?.startsWith('chrome://') || tab.url?.startsWith('chrome-extension://')) {
+      const err = `Cannot attach to browser page: ${tab.url}`;
+      debuggerState.lastError = err;
+      return callback({ success: false, error: err });
+    }
+
+    // Detach from previous tab if different
+    if (debuggerState.attached && debuggerState.tabId && debuggerState.tabId !== tabId) {
+      chrome.debugger.detach({ tabId: debuggerState.tabId }, () => {});
+    }
+
+    chrome.debugger.attach({ tabId }, '1.3', () => {
+      if (chrome.runtime.lastError) {
+        const err = chrome.runtime.lastError.message;
+        debuggerState.lastError = err;
+        debuggerState.attached = false;
+        return callback({ success: false, error: err });
+      }
+
+      debuggerState.attached = true;
+      debuggerState.tabId = tabId;
+      debuggerState.domainsEnabled = false;
+      debuggerState.attachmentTime = Date.now();
+
+      enableCDPDomains(tabId, () => {
+        debuggerState.domainsEnabled = true;
+        // Make sure offscreen WS bridge is running
+        ensureOffscreen();
+        callback({ success: true, tabId });
+      });
+    });
+  });
+}
+
+function detachDebugger(callback) {
+  if (!debuggerState.tabId) {
+    debuggerState = { attached: false, tabId: null, domainsEnabled: false, lastError: null, attachmentTime: null };
+    return callback({ success: true });
+  }
+  chrome.debugger.detach({ tabId: debuggerState.tabId }, () => {
+    debuggerState = { attached: false, tabId: null, domainsEnabled: false, lastError: null, attachmentTime: null };
+    callback({ success: true });
+  });
+}
+
+function enableCDPDomains(tabId, done) {
+  const domains = ['DOM', 'CSS', 'Page', 'Overlay'];
+  let i = 0;
+  const next = () => {
+    if (i >= domains.length) return done();
+    const domain = domains[i++];
+    chrome.debugger.sendCommand({ tabId }, `${domain}.enable`, {}, () => {
+      if (chrome.runtime.lastError) {
+        console.warn(`[gravity] failed to enable ${domain}:`, chrome.runtime.lastError.message);
+      }
+      next();
+    });
+  };
+  next();
+}
+
+// ── Chrome events ─────────────────────────────────────────────────────────────
+
+chrome.debugger.onDetach.addListener((source, reason) => {
+  if (source.tabId === debuggerState.tabId) {
+    debuggerState = {
+      attached: false, tabId: null, domainsEnabled: false,
+      lastError: reason === 'target_closed' ? 'Tab was closed' : `Detached: ${reason}`,
+      attachmentTime: null,
+    };
+  }
+  chrome.runtime.sendMessage({ action: 'debugger_detached', tabId: source.tabId, reason }).catch(() => {});
+});
+
+chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  if (tabId === debuggerState.tabId && changeInfo.status === 'loading') {
+    debuggerState.domainsEnabled = false;
+  }
+});
+
+chrome.tabs.onRemoved.addListener((tabId) => {
+  if (tabId === debuggerState.tabId) {
+    debuggerState = { attached: false, tabId: null, domainsEnabled: false, lastError: 'Tab was closed', attachmentTime: null };
+  }
+});
+
+// ── Boot — ensure offscreen doc is alive on SW startup ───────────────────────
+ensureOffscreen();

package/extension/icon128.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" class="icon icon-tabler icons-tabler-filled icon-tabler-settings"><path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M14.647 4.081a.724 .724 0 0 0 1.08 .448c2.439 -1.485 5.23 1.305 3.745 3.744a.724 .724 0 0 0 .447 1.08c2.775 .673 2.775 4.62 0 5.294a.724 .724 0 0 0 -.448 1.08c1.485 2.439 -1.305 5.23 -3.744 3.745a.724 .724 0 0 0 -1.08 .447c-.673 2.775 -4.62 2.775 -5.294 0a.724 .724 0 0 0 -1.08 -.448c-2.439 1.485 -5.23 -1.305 -3.745 -3.744a.724 .724 0 0 0 -.447 -1.08c-2.775 -.673 -2.775 -4.62 0 -5.294a.724 .724 0 0 0 .448 -1.08c-1.485 -2.439 1.305 -5.23 3.744 -3.745a.722 .722 0 0 0 1.08 -.447c.673 -2.775 4.62 -2.775 5.294 0zm-2.647 4.919a3 3 0 1 0 0 6a3 3 0 0 0 0 -6z" /></svg>

package/extension/icon16.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="icon icon-tabler icons-tabler-outline icon-tabler-rocket"><path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M4 13a8 8 0 0 1 7 7a6 6 0 0 0 3 -5a9 9 0 0 0 6 -8a3 3 0 0 0 -3 -3a9 9 0 0 0 -8 6a6 6 0 0 0 -5 3" /><path d="M7 14a6 6 0 0 0 -3 6a6 6 0 0 0 6 -3" /><path d="M15 9m-1 0a1 1 0 1 0 2 0a1 1 0 1 0 -2 0" /></svg>

package/extension/icon48.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="icon icon-tabler icons-tabler-outline icon-tabler-world"><path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M3 12a9 9 0 1 0 18 0a9 9 0 0 0 -18 0" /><path d="M3.6 9h16.8" /><path d="M3.6 15h16.8" /><path d="M11.5 3a17 17 0 0 0 0 18" /><path d="M12.5 3a17 17 0 0 1 0 18" /></svg>

package/extension/manifest.json

@@ -0,0 +1,24 @@
+{
+  "manifest_version": 3,
+  "name": "Gravity",
+  "version": "3.0.0",
+  "description": "AI-powered CSS layout diagnostics — connects to local MCP server",
+  "permissions": [
+    "debugger",
+    "activeTab",
+    "tabs",
+    "offscreen"
+  ],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "action": {
+    "default_popup": "popup.html",
+    "default_icon": {
+      "16": "icon16.svg",
+      "48": "icon48.svg",
+      "128": "icon128.svg"
+    }
+  }
+}

package/extension/offscreen.html

@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<!-- Gravity offscreen document — holds the WebSocket bridge alive permanently.
+     Chrome MV3 offscreen documents with an active WebSocket are not suspended. -->
+<script src="offscreen.js"></script>

package/extension/offscreen.js

@@ -0,0 +1,74 @@
+// =============================================================================
+// Gravity v3 — Offscreen Document
+//
+// Lives permanently (Chrome keeps offscreen docs alive while a WebSocket is
+// open). Owns the WS connection to the MCP server bridge on :9224.
+//
+// Message flow:
+//   SW  →  chrome.runtime.sendMessage({ to:'offscreen', ... })  →  here
+//   here → chrome.runtime.sendMessage({ to:'sw', ... })         →  SW
+// =============================================================================
+
+const WS_PORT = 9224;
+const RECONNECT_MS = 2000;
+
+let ws = null;
+let wsReady = false;
+
+// ── WebSocket to MCP server ───────────────────────────────────────────────────
+
+function connect() {
+  if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+
+  try {
+    ws = new WebSocket(`ws://127.0.0.1:${WS_PORT}`);
+
+    ws.onopen = () => {
+      wsReady = true;
+      // Tell SW the bridge is up so it can update the popup
+      chrome.runtime.sendMessage({ to: 'sw', type: 'ws_status', connected: true }).catch(() => {});
+    };
+
+    ws.onmessage = ({ data }) => {
+      try {
+        const msg = JSON.parse(data);
+        // Forward CDP requests from MCP server → SW (which has chrome.debugger)
+        if (msg.type === 'cdp_request') {
+          chrome.runtime.sendMessage({ to: 'sw', type: 'cdp_request', payload: msg }).catch(() => {});
+        }
+      } catch (e) {
+        console.error('[gravity/offscreen] parse error', e);
+      }
+    };
+
+    ws.onclose = () => {
+      wsReady = false;
+      ws = null;
+      chrome.runtime.sendMessage({ to: 'sw', type: 'ws_status', connected: false }).catch(() => {});
+      setTimeout(connect, RECONNECT_MS);
+    };
+
+    ws.onerror = () => {
+      // onclose fires right after, handles retry
+    };
+  } catch (e) {
+    console.error('[gravity/offscreen] WS create failed', e);
+    setTimeout(connect, RECONNECT_MS);
+  }
+}
+
+// ── Receive CDP responses from SW, forward to MCP server ─────────────────────
+
+chrome.runtime.onMessage.addListener((msg) => {
+  if (msg.to !== 'offscreen') return;
+
+  if (msg.type === 'cdp_response') {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg.payload));
+    }
+  }
+});
+
+// ── Boot ──────────────────────────────────────────────────────────────────────
+
+connect();

package/extension/popup.html

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      width: 280px;
+      padding: 16px;
+      font-family: system-ui, -apple-system, sans-serif;
+      font-size: 13px;
+      color: #1a1a1a;
+      background: #fff;
+    }
+    h3 { font-size: 15px; font-weight: 600; margin-bottom: 12px; }
+
+    .row {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 8px;
+    }
+    .dot {
+      width: 10px; height: 10px;
+      border-radius: 50%;
+      flex-shrink: 0;
+    }
+    .dot.green  { background: #22c55e; }
+    .dot.red    { background: #ef4444; }
+    .dot.yellow { background: #eab308; }
+
+    .label { color: #555; min-width: 80px; }
+    .value { font-weight: 500; }
+
+    hr { border: none; border-top: 1px solid #eee; margin: 12px 0; }
+
+    button {
+      width: 100%;
+      padding: 8px 12px;
+      border: none;
+      border-radius: 6px;
+      font-size: 13px;
+      font-weight: 500;
+      cursor: pointer;
+      transition: background 0.15s;
+    }
+    #toggleBtn {
+      background: #2563eb;
+      color: #fff;
+      margin-bottom: 6px;
+    }
+    #toggleBtn:hover { background: #1d4ed8; }
+    #toggleBtn.disconnect { background: #dc2626; }
+    #toggleBtn.disconnect:hover { background: #b91c1c; }
+
+    .hint {
+      font-size: 11px;
+      color: #888;
+      margin-top: 10px;
+      line-height: 1.5;
+    }
+    .hint code {
+      background: #f3f4f6;
+      padding: 1px 4px;
+      border-radius: 3px;
+      font-size: 11px;
+    }
+    .error-msg {
+      font-size: 11px;
+      color: #dc2626;
+      margin-top: 4px;
+      display: none;
+    }
+  </style>
+</head>
+<body>
+  <h3>⚡ Gravity</h3>
+
+  <div class="row">
+    <span class="label">Debugger</span>
+    <div id="debugDot" class="dot red"></div>
+    <span id="debugText" class="value">Disconnected</span>
+  </div>
+  <div class="row">
+    <span class="label">MCP Server</span>
+    <div id="mcpDot" class="dot red"></div>
+    <span id="mcpText" class="value">Not running</span>
+  </div>
+
+  <div id="errorMsg" class="error-msg"></div>
+
+  <hr>
+
+  <button id="toggleBtn">Connect to Tab</button>
+
+  <div class="hint">
+    <strong>Setup (once):</strong><br>
+    1. Add <code>gravity</code> to your MCP config<br>
+    2. Click "Connect to Tab" above<br>
+    3. Ask AI: <em>"diagnose #header"</em>
+  </div>
+
+  <script src="popup.js"></script>
+</body>
+</html>

package/extension/popup.js

@@ -0,0 +1,84 @@
+// popup.js — Gravity v3 (MV3 compatible)
+const debugDot  = document.getElementById('debugDot');
+const debugText = document.getElementById('debugText');
+const mcpDot    = document.getElementById('mcpDot');
+const mcpText   = document.getElementById('mcpText');
+const toggleBtn = document.getElementById('toggleBtn');
+const errorMsg  = document.getElementById('errorMsg');
+
+function setDot(dot, text, state, label) {
+  dot.className = 'dot ' + state;
+  text.textContent = label;
+}
+
+function showError(msg) {
+  errorMsg.style.display = msg ? 'block' : 'none';
+  errorMsg.textContent = msg || '';
+}
+
+function render(status) {
+  showError(null);
+
+  // Debugger row
+  if (status.attached && status.domainsEnabled) {
+    setDot(debugDot, debugText, 'green', `Tab ${status.tabId}`);
+  } else if (status.attached) {
+    setDot(debugDot, debugText, 'yellow', 'Attaching…');
+  } else {
+    setDot(debugDot, debugText, 'red', 'Disconnected');
+    if (status.lastError) showError(status.lastError);
+  }
+
+  // MCP server row
+  if (status.wsConnected) {
+    setDot(mcpDot, mcpText, 'green', 'Connected');
+  } else {
+    setDot(mcpDot, mcpText, 'red', 'Not running');
+  }
+
+  // Button
+  if (status.attached) {
+    toggleBtn.textContent = 'Disconnect';
+    toggleBtn.classList.add('disconnect');
+  } else {
+    toggleBtn.textContent = 'Connect to Tab';
+    toggleBtn.classList.remove('disconnect');
+  }
+}
+
+function refresh() {
+  // In MV3, sendMessage may fail if SW is sleeping — retry once
+  chrome.runtime.sendMessage({ action: 'status' }, (status) => {
+    if (chrome.runtime.lastError) {
+      // SW waking up — retry after short delay
+      setTimeout(() => {
+        chrome.runtime.sendMessage({ action: 'status' }, (s) => {
+          if (!chrome.runtime.lastError && s) render(s);
+        });
+      }, 300);
+      return;
+    }
+    if (status) render(status);
+  });
+}
+
+toggleBtn.addEventListener('click', () => {
+  toggleBtn.disabled = true;
+  chrome.runtime.sendMessage({ action: 'status' }, (status) => {
+    const action = (status && status.attached) ? 'detach' : 'attach';
+    chrome.runtime.sendMessage({ action }, (response) => {
+      toggleBtn.disabled = false;
+      if (response && !response.success && response.error) showError(response.error);
+      refresh();
+    });
+  });
+});
+
+// Listen for real-time status pushes from SW (ws_status_update)
+chrome.runtime.onMessage.addListener((msg) => {
+  if (msg.action === 'ws_status_update') refresh();
+  if (msg.action === 'debugger_detached') refresh();
+});
+
+refresh();
+setInterval(refresh, 2000);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "gravity-lite",
+  "version": "3.0.0",
+  "description": "AI-powered CSS layout diagnostics — zero-config MCP server for developers",
+  "type": "module",
+  "bin": {
+    "gravity": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^11.0.0",
+    "ws": "^8.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "extension",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "css",
+    "layout",
+    "diagnostics",
+    "devtools",
+    "chrome",
+    "ai",
+    "kiro",
+    "cursor",
+    "claude",
+    "accessibility",
+    "wcag"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DharuNamikaze/gravity"
+  },
+  "homepage": "https://github.com/DharuNamikaze/gravity#readme",
+  "bugs": {
+    "url": "https://github.com/DharuNamikaze/gravity/issues"
+  },
+  "author": "DharuNamikaze"
+}