pixelpick 2.0.0

package/dist/chrome-mv3/src/inspector/react-detector.js

@@ -0,0 +1,225 @@
+// React component detection via Fiber introspection
+import { REACT_CONFIG } from '../constants.js';
+
+/**
+ * Detects which framework (if any) is used by the element
+ * @param {HTMLElement} element
+ * @returns {string|null} - Framework name or null
+ */
+export function detectFramework(element) {
+  // React: Check for __reactFiber$ or __reactInternalInstance$ property
+  const fiberKey = Object.keys(element).find(k =>
+    REACT_CONFIG.FIBER_KEY_PATTERNS.some(pattern => k.startsWith(pattern))
+  );
+
+  if (fiberKey) return 'react';
+
+  // Future: Vue, Svelte, etc.
+  return null;
+}
+
+/**
+ * Gets the component name from a React fiber
+ * @param {Object} fiber - React fiber object
+ * @returns {string|null}
+ */
+export function getComponentName(fiber) {
+  if (!fiber || !fiber.type) return null;
+
+  // Function component or class component
+  if (typeof fiber.type === 'function') {
+    return fiber.type.displayName || fiber.type.name || 'Anonymous';
+  }
+
+  return null;
+}
+
+/**
+ * Detects React version
+ * @returns {string} - React version or 'unknown'
+ */
+export function getReactVersion() {
+  try {
+    // Check for React in window
+    if (window.React) {
+      const internals = window.React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
+      return internals?.ReactVersion || 'unknown';
+    }
+
+    // Try to detect from fiber
+    const rootElements = document.querySelectorAll('[id*="root"]');
+    for (const root of rootElements) {
+      const fiberKey = Object.keys(root).find(k =>
+        k.startsWith(REACT_CONFIG.CONTAINER_KEY_PATTERN)
+      );
+      if (fiberKey) {
+        // Heuristic: React 18+ uses __reactContainer
+        return '18+';
+      }
+    }
+
+    return 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Sanitizes React props for safe serialization
+ * @param {Object} props - React component props
+ * @returns {Object|null}
+ */
+export function sanitizeProps(props) {
+  if (!props || typeof props !== 'object') return null;
+
+  const sanitized = {};
+
+  for (const [key, value] of Object.entries(props)) {
+    // Skip children (too large)
+    if (key === 'children') continue;
+
+    try {
+      // Handle functions
+      if (typeof value === 'function') {
+        sanitized[key] = `[Function: ${value.name || 'anonymous'}]`;
+        continue;
+      }
+
+      // Handle symbols
+      if (typeof value === 'symbol') {
+        continue;
+      }
+
+      // Handle objects (with truncation)
+      if (typeof value === 'object' && value !== null) {
+        const str = JSON.stringify(value);
+        if (str.length > REACT_CONFIG.MAX_PROPS_LENGTH) {
+          sanitized[key] = str.slice(0, REACT_CONFIG.MAX_PROPS_LENGTH) + '...';
+        } else {
+          sanitized[key] = value;
+        }
+        continue;
+      }
+
+      // Primitives
+      sanitized[key] = value;
+    } catch (err) {
+      // Circular reference or other error
+      sanitized[key] = '[Object]';
+    }
+  }
+
+  return Object.keys(sanitized).length > 0 ? sanitized : null;
+}
+
+/**
+ * Builds component tree by walking up the fiber tree
+ * @param {Object} fiber - Starting React fiber
+ * @param {number} maxDepth - Maximum depth to traverse
+ * @returns {Array<string>|null}
+ */
+export function buildComponentTree(fiber, maxDepth = REACT_CONFIG.MAX_COMPONENT_TREE_DEPTH) {
+  const tree = [];
+  let current = fiber;
+  let depth = 0;
+
+  while (current && depth < maxDepth) {
+    if (typeof current.type !== 'string') {
+      const name = getComponentName(current);
+      if (name) {
+        tree.push(name);
+      }
+    }
+
+    current = current.return;
+    depth++;
+  }
+
+  return tree.length > 0 ? tree.reverse() : null;
+}
+
+/**
+ * Extracts React component data from a DOM element
+ * @param {HTMLElement} element
+ * @returns {Object|null} - Component data or null
+ */
+export function extractReactData(element) {
+  try {
+    // Find fiber key
+    const fiberKey = Object.keys(element).find(k =>
+      REACT_CONFIG.FIBER_KEY_PATTERNS.some(pattern => k.startsWith(pattern))
+    );
+
+    if (!fiberKey) {
+      return null;
+    }
+
+    const fiber = element[fiberKey];
+    if (!fiber) return null;
+
+    // Walk up to find component fiber (skip host fibers like 'div')
+    let componentFiber = fiber;
+    while (componentFiber && typeof componentFiber.type === 'string') {
+      componentFiber = componentFiber.return;
+      if (!componentFiber) break;
+    }
+
+    if (!componentFiber) {
+      return {
+        name: null,
+        props: null,
+        fileLocation: null,
+        tree: null,
+      };
+    }
+
+    // Extract component name
+    const name = getComponentName(componentFiber);
+
+    // Extract props
+    const props = sanitizeProps(componentFiber.memoizedProps);
+
+    // Extract file location
+    let fileLocation = null;
+
+    // Try _debugSource (React 18)
+    if (componentFiber._debugSource) {
+      const src = componentFiber._debugSource;
+      fileLocation = `${src.fileName}:${src.lineNumber}:${src.columnNumber}`;
+    } else {
+      // Fallback: Parse stack trace (React 19)
+      try {
+        const stack = new Error().stack;
+        const lines = stack.split('\n');
+        // Find first non-node_modules line
+        for (const line of lines) {
+          if (line.includes('.jsx') || line.includes('.tsx') || line.includes('.js')) {
+            if (!line.includes('node_modules') && !line.includes('inspector.js')) {
+              // Extract file:line from stack trace
+              const match = line.match(/([^/\s]+\.(jsx?|tsx?)):(\d+):(\d+)/);
+              if (match) {
+                fileLocation = `${match[1]}:${match[3]}`;
+                break;
+              }
+            }
+          }
+        }
+      } catch {
+        // Stack parsing failed
+      }
+    }
+
+    // Build component tree
+    const tree = buildComponentTree(componentFiber);
+
+    return {
+      name,
+      props,
+      fileLocation,
+      tree,
+    };
+  } catch (err) {
+    console.error('[PixelPick] React extraction error:', err);
+    return null;
+  }
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "pixelpick",
+  "version": "2.0.0",
+  "description": "Visual UI inspector for Claude Code via MCP",
+  "type": "module",
+  "bin": {
+    "pixelpick": "src/cli/index.js",
+    "pixelpick-server": "src/server/index.js",
+    "pixelpick-check-selection": "src/hooks/check-selection.mjs"
+  },
+  "files": [
+    "src/",
+    "dist/chrome-mv3/",
+    "public/icon/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "wxt",
+    "build": "wxt build",
+    "build:firefox": "wxt build --browser firefox",
+    "zip": "wxt zip",
+    "start": "node src/server/index.js",
+    "test": "node --test tests/**/*.test.js",
+    "serve-test": "node tests/helpers/serve-test.js",
+    "test:react": "npm run test:ensure-deps && cd tests/react-app && npm run dev",
+    "test:ensure-deps": "[ -d tests/react-app/node_modules ] || (echo '\nInstalling React test app dependencies...\n' && cd tests/react-app && npm install)",
+    "test:setup": "cd tests/react-app && npm install",
+    "generate-icons": "node scripts/generate-icons.mjs",
+    "prepublishOnly": "wxt build",
+    "postinstall": "chmod +x src/cli/index.js src/server/index.js src/hooks/check-selection.mjs 2>/dev/null || true"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.16.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "model-context-protocol",
+    "ui-inspector",
+    "developer-tools",
+    "chrome-extension",
+    "react"
+  ],
+  "license": "MIT",
+  "author": "bilune",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bilune/pixelpick.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bilune/pixelpick/issues"
+  },
+  "homepage": "https://github.com/bilune/pixelpick#readme",
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/chrome": "^0.1.36",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@wxt-dev/module-react": "^1.1.5",
+    "autoprefixer": "^10.4.24",
+    "lucide-react": "^0.564.0",
+    "postcss": "^8.5.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.9.3",
+    "wxt": "^0.20.17"
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const command = process.argv[2];
+
+// Flip to true once Chrome Web Store listing is approved
+const WEB_STORE_AVAILABLE = false;
+const WEB_STORE_URL = ''; // e.g. https://chrome.google.com/webstore/detail/pixelpick/...
+
+switch (command) {
+  case 'init':
+    init();
+    break;
+  case 'start':
+  case undefined:
+    startServer();
+    break;
+  case 'status':
+    checkStatus();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+  case '--version':
+  case '-v':
+    showVersion();
+    break;
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    showHelp();
+    process.exit(1);
+}
+
+function init() {
+  const isProjectScope = process.argv.includes('--project');
+  const scope = isProjectScope ? 'project' : 'user';
+
+  console.log('PixelPick -- Setting up Claude Code integration...\n');
+
+  // Step 0: Check prerequisites
+  console.log('[1/4] Checking prerequisites...');
+  try {
+    execSync('claude --version', { stdio: 'pipe' });
+    console.log('      Claude CLI found.\n');
+  } catch {
+    console.error('      Claude CLI not found.\n');
+    console.error('      Install it first:');
+    console.error('        npm install -g @anthropic-ai/claude-code\n');
+    console.error('      Then run this command again: npx pixelpick init');
+    process.exit(1);
+  }
+
+  // Step 1: Register MCP server
+  console.log('[2/4] Registering MCP server...');
+  try {
+    const serverPath = join(__dirname, '../server/index.js');
+    try {
+      execSync(
+        `claude mcp add --scope ${scope} pixelpick -- node "${serverPath}"`,
+        { stdio: 'pipe' }
+      );
+      console.log('      MCP server registered.\n');
+    } catch (addErr) {
+      // Check if it already exists
+      const listOutput = execSync('claude mcp list', { encoding: 'utf8', stdio: 'pipe' });
+      if (listOutput.includes('pixelpick')) {
+        console.log('      MCP server already registered (skipped).\n');
+      } else {
+        throw addErr;
+      }
+    }
+  } catch (err) {
+    console.error('      Failed to register MCP server.');
+    console.error('      Error:', err.message);
+    process.exit(1);
+  }
+
+  // Step 2: Add UserPromptSubmit hook
+  console.log('[3/4] Installing selection injection hook...');
+  const settingsPath = isProjectScope
+    ? join(process.cwd(), '.claude', 'settings.json')
+    : join(process.env.HOME, '.claude', 'settings.json');
+
+  try {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    let settings = {};
+    if (existsSync(settingsPath)) {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    }
+
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+    // Check if hook already exists
+    const hookExists = settings.hooks.UserPromptSubmit.some(
+      h => h.hooks?.some(hook => hook.command?.includes('pixelpick'))
+    );
+
+    if (!hookExists) {
+      const checkSelectionPath = join(__dirname, '../hooks/check-selection.mjs');
+      settings.hooks.UserPromptSubmit.push({
+        hooks: [{
+          type: 'command',
+          command: `node "${checkSelectionPath}"`,
+          timeout: 2000
+        }]
+      });
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+      console.log('      Hook installed.\n');
+    } else {
+      console.log('      Hook already installed (skipped).\n');
+    }
+  } catch (err) {
+    console.error('      Failed to install hook:', err.message);
+    process.exit(1);
+  }
+
+  // Step 3: Chrome Extension guidance
+  console.log('[4/4] Chrome Extension...');
+
+  if (WEB_STORE_AVAILABLE) {
+    console.log(`      Install from Chrome Web Store:`);
+    console.log(`      ${WEB_STORE_URL}\n`);
+  } else {
+    // Find the built extension in the package
+    const extensionPath = join(__dirname, '../../dist/chrome-mv3');
+
+    if (existsSync(extensionPath)) {
+      console.log('      Load the extension manually:\n');
+      console.log(`      1. Open chrome://extensions`);
+      console.log(`      2. Enable "Developer mode" (top right)`);
+      console.log(`      3. Click "Load unpacked"`);
+      console.log(`      4. Select: ${extensionPath}\n`);
+
+      // Try to copy path to clipboard (macOS)
+      try {
+        execSync(`echo "${extensionPath}" | pbcopy`, { stdio: 'pipe' });
+        console.log('      (Extension path copied to clipboard)\n');
+      } catch {
+        // Silent fail -- pbcopy not available on Linux/Windows
+      }
+
+      // Try to open chrome://extensions
+      try {
+        execSync('open "chrome://extensions"', { stdio: 'pipe' });
+      } catch {
+        // Silent fail -- not macOS or Chrome not default browser
+      }
+    } else {
+      console.log('      Extension build not found. Build it first:\n');
+      console.log('        cd node_modules/pixelpick && npm run build\n');
+      console.log('      Then load dist/chrome-mv3/ as unpacked extension.');
+      console.log('      See: https://github.com/bilune/pixelpick#setup\n');
+    }
+  }
+
+  // Done
+  console.log('--- Setup complete! ---\n');
+  console.log('How to use:');
+  console.log('  1. Open your app in Chrome (localhost)');
+  console.log('  2. Cmd+Shift+Click on any element');
+  console.log('  3. Switch to Claude Code and describe your change');
+  console.log('  4. Claude automatically sees what you selected\n');
+  console.log('Verify: npx pixelpick status');
+}
+
+function startServer() {
+  import('../server/index.js');
+}
+
+async function checkStatus() {
+  console.log('PixelPick Status');
+  console.log('-'.repeat(42) + '\n');
+
+  // Check MCP server
+  let serverRunning = false;
+
+  try {
+    const response = await fetch('http://127.0.0.1:9316/status');
+    const data = await response.json();
+    serverRunning = true;
+    console.log(`MCP Server:        Running (localhost:${data.ports.websocket})`);
+    console.log(`Active Connections: ${data.connections}`);
+
+    // Get active selections
+    const selectionResponse = await fetch('http://127.0.0.1:9316/selection');
+    const selections = await selectionResponse.json();
+    if (Array.isArray(selections) && selections.length > 0) {
+      console.log(`Active Selections: ${selections.length}`);
+      selections.forEach((sel, idx) => {
+        const label = sel.component
+          ? `${sel.component} (${sel.framework})`
+          : `<${sel.tagName}>`;
+        const age = Math.round((Date.now() - sel.timestamp) / 1000);
+        console.log(`  [${idx + 1}] ${label} - ${age}s ago`);
+      });
+    } else {
+      console.log('Active Selections: None');
+    }
+  } catch {
+    console.log('MCP Server:        Not running');
+    console.log('                   Run: npx pixelpick start');
+  }
+
+  // Check Claude Code registration
+  try {
+    const result = execSync('claude mcp list', { encoding: 'utf8', stdio: 'pipe' });
+    if (result.includes('pixelpick')) {
+      console.log('Claude Code:       Registered');
+    } else {
+      console.log('Claude Code:       Not registered');
+      console.log('                   Run: npx pixelpick init');
+    }
+  } catch {
+    console.log('Claude Code:       Could not check');
+  }
+
+  // Check hook
+  try {
+    const settingsPath = join(process.env.HOME, '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const hasHook = settings.hooks?.UserPromptSubmit?.some(
+        h => h.hooks?.some(hook => hook.command?.includes('pixelpick'))
+      );
+      if (hasHook) {
+        console.log('UserPrompt Hook:   Installed');
+      } else {
+        console.log('UserPrompt Hook:   Not installed');
+        console.log('                   Run: npx pixelpick init');
+      }
+    }
+  } catch {
+    console.log('UserPrompt Hook:   Could not check');
+  }
+
+  console.log();
+}
+
+function showHelp() {
+  console.log(`
+PixelPick -- Visual UI inspector for Claude Code
+
+Commands:
+  pixelpick init       Set up MCP server, hooks, and extension
+  pixelpick start      Start the MCP server
+  pixelpick status     Check connection status
+  pixelpick help       Show this help message
+
+Options:
+  --project            Use project scope instead of user scope (for init)
+  --version, -v        Show version number
+
+Environment Variables:
+  PIXELPICK_PORT       WebSocket port (default: 9315)
+  PIXELPICK_IPC_PORT   HTTP IPC port (default: 9316)
+
+More info: https://github.com/bilune/pixelpick
+`);
+}
+
+function showVersion() {
+  try {
+    const pkgPath = join(__dirname, '../../package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    console.log(`pixelpick v${pkg.version}`);
+  } catch {
+    console.log('pixelpick (version unknown)');
+  }
+}

package/src/hooks/check-selection.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import http from 'http';
+import { PORTS, SELECTION } from '../shared/constants.js';
+
+const IPC_PORT = PORTS.IPC;
+
+async function checkSelection() {
+  return new Promise((resolve) => {
+    const req = http.get(
+      `http://127.0.0.1:${IPC_PORT}/selection`,
+      { timeout: SELECTION.IPC_TIMEOUT }, // Fast timeout - must not delay prompts
+      (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            const selections = JSON.parse(data);
+            resolve(selections);
+          } catch {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on('error', () => resolve(null)); // Server not running = no selections
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function clearSelections() {
+  return new Promise((resolve) => {
+    const postData = '';
+    const options = {
+      hostname: '127.0.0.1',
+      port: IPC_PORT,
+      path: '/selection/clear',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+      timeout: SELECTION.IPC_TIMEOUT,
+    };
+
+    const req = http.request(options, (res) => {
+      // Silent success
+      resolve(true);
+    });
+
+    req.on('error', () => resolve(false)); // Silent failure
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.write(postData);
+    req.end();
+  });
+}
+
+async function main() {
+  const selections = await checkSelection();
+
+  // If no selections or invalid data, exit silently
+  if (!selections || !Array.isArray(selections) || selections.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Build formatted context for multiple selections
+  const parts = ['[PixelPick — Active Browser Selections]'];
+
+  selections.forEach((selection, idx) => {
+    parts.push(`\n[${idx + 1}] ─────────────────`);
+
+    if (selection.component) {
+      parts.push(`Component: ${selection.component} (${selection.framework})`);
+    } else {
+      parts.push(`Element: <${selection.tagName}>`);
+    }
+
+    if (selection.fileLocation) {
+      parts.push(`File: ${selection.fileLocation}`);
+    }
+
+    parts.push(`Selector: ${selection.selector}`);
+
+    if (selection.componentTree?.length) {
+      parts.push(`Tree: ${selection.componentTree.join(' > ')}`);
+    }
+
+    // Always show full props (no compact mode)
+    if (selection.props && Object.keys(selection.props).length > 0) {
+      parts.push(`Props: ${JSON.stringify(selection.props, null, 0)}`);
+    }
+
+    if (selection.styles?._tailwindClasses?.length) {
+      parts.push(`Tailwind: ${selection.styles._tailwindClasses.join(' ')}`);
+    }
+
+    if (selection.accessibility?.isInteractive) {
+      const a11y = [];
+      if (selection.accessibility.role) a11y.push(`role="${selection.accessibility.role}"`);
+      if (selection.accessibility.ariaLabel) a11y.push(`aria-label="${selection.accessibility.ariaLabel}"`);
+      if (a11y.length > 0) {
+        parts.push(`A11y: ${a11y.join(', ')}`);
+      }
+    }
+  });
+
+  const context = parts.join('\n');
+
+  // Output as JSON with additionalContext
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: context
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output));
+
+  // Auto-clear selections after injection (fire-and-forget)
+  clearSelections().then(() => process.exit(0));
+}
+
+main();