@createlex/figgen 1.4.2

package/companion/bridge-server.cjs

@@ -0,0 +1,786 @@
+const express = require('express');
+const cors = require('cors');
+const http = require('http');
+const { execFile } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { WebSocketServer, WebSocket } = require('ws');
+const {
+  GENERATED_ROOT_DIRNAME,
+  GENERATED_LAYOUT_VERSION,
+  getSavedProjectPath,
+  resolveWritableProjectPath,
+  setSavedProjectPath,
+  writeSwiftUIScreen,
+} = require('./xcode-writer.cjs');
+const { buildGenerationPrompt } = require('./local-llm-generator.cjs');
+
+const DEFAULT_PORT = 7765;
+const DEFAULT_HOST = 'localhost';
+const BRIDGE_PROTOCOL_VERSION = 1;
+const SUPPORTED_BRIDGE_ACTIONS = [
+  'ping',
+  'get_document_summary',
+  'get_metadata',
+  'get_design_context',
+  'get_screenshot',
+  'export_svg',
+  'get_viewport_context',
+  'get_selection_snapshot',
+  'get_page_snapshot',
+  'get_node_snapshot',
+  'find_nodes',
+  'dump_tree',
+  'get_asset_export_plan',
+  'extract_reusable_components',
+  'generate_swiftui',
+  'analyze_generation',
+];
+
+function normalizeLogger(logger = {}) {
+  return {
+    info: typeof logger.info === 'function' ? logger.info.bind(logger) : console.log,
+    warn: typeof logger.warn === 'function' ? logger.warn.bind(logger) : console.warn,
+    error: typeof logger.error === 'function' ? logger.error.bind(logger) : console.error,
+  };
+}
+
+async function waitForExistingBridge({ host, port }) {
+  try {
+    const response = await fetch(`http://${host}:${port}/bridge/info`);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const data = await response.json();
+
+    // Verify WebSocket is also healthy, not just HTTP
+    await new Promise((resolve, reject) => {
+      const testWs = new WebSocket(`ws://${host}:${port}/bridge`);
+      const timeout = setTimeout(() => {
+        testWs.terminate();
+        reject(new Error('WebSocket health check timed out'));
+      }, 3000);
+      testWs.on('open', () => {
+        clearTimeout(timeout);
+        testWs.close();
+        resolve();
+      });
+      testWs.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(new Error(`WebSocket health check failed: ${err.message}`));
+      });
+    });
+
+    return {
+      ok: true,
+      alreadyRunning: true,
+      info: data,
+    };
+  } catch (error) {
+    throw new Error(`Port ${port} is already in use and does not look like a healthy Figma SwiftUI bridge (${error.message})`);
+  }
+}
+
+async function killStaleAndRetry({ host, port, logger }) {
+  const { execSync } = require('child_process');
+  try {
+    const lsofOutput = execSync(`lsof -ti :${port}`, { encoding: 'utf8' }).trim();
+    const pids = lsofOutput.split('\n').filter(Boolean);
+    if (pids.length > 0) {
+      logger.warn(`⚠️  Killing ${pids.length} stale process(es) on port ${port}: ${pids.join(', ')}`);
+      for (const pid of pids) {
+        try { process.kill(Number(pid), 'SIGTERM'); } catch (_) {}
+      }
+      // Wait for port to free up
+      await new Promise((r) => setTimeout(r, 1500));
+    }
+  } catch (_) {
+    // lsof returns non-zero if no matches — port is already free
+  }
+}
+
+function startBridgeServer(options = {}) {
+  const port = Number(options.port || process.env.FIGMA_SWIFTUI_BRIDGE_PORT || DEFAULT_PORT);
+  const host = options.host || process.env.FIGMA_SWIFTUI_BRIDGE_HOST || DEFAULT_HOST;
+  const logger = normalizeLogger(options.logger);
+  const app = express();
+  const server = http.createServer(app);
+
+  let projectPath = options.projectPath ? setSavedProjectPath(options.projectPath) : getSavedProjectPath();
+  let pluginBridgeClient = null;
+  const agentBridgeClients = new Set();
+  const passivePluginClients = new Set();
+  const pendingBridgeRequests = new Map();
+
+  app.use(cors({ origin: '*' }));
+  app.use(express.json({ limit: '50mb' }));
+
+  // Auth state exposed to the plugin UI via /ping
+  let authRequired = false;
+  let authRequiredReason = null;
+
+  function setAuthRequired(reason) {
+    authRequired = true;
+    authRequiredReason = reason || 'Token expired';
+    logger.warn(`[figma-swiftui-bridge] Auth required: ${authRequiredReason}`);
+  }
+
+  app.get('/ping', (req, res) => {
+    if (authRequired) {
+      return res.status(401).json({
+        ok: false,
+        authRequired: true,
+        authRequiredReason,
+        loginCommand: 'npx @createlex/figma-swiftui-mcp login',
+      });
+    }
+    res.json({
+      ok: true,
+      projectPath: projectPath || null,
+      generatedRoot: projectPath ? path.join(projectPath, GENERATED_ROOT_DIRNAME) : null,
+      layoutVersion: GENERATED_LAYOUT_VERSION,
+    });
+  });
+
+  // Graceful shutdown — called by the plugin UI "Disconnect MCP" to stop the runtime
+  app.post('/shutdown', (req, res) => {
+    res.json({ ok: true, message: 'Shutting down bridge server…' });
+    logger.info('[figma-swiftui-bridge] Shutdown requested by plugin UI');
+    setTimeout(() => process.exit(0), 400);
+  });
+
+  app.get('/bridge/info', (req, res) => {
+    res.json({
+      ok: true,
+      protocolVersion: BRIDGE_PROTOCOL_VERSION,
+      wsUrl: `ws://${host}:${port}/bridge`,
+      pluginConnected: !!pluginBridgeClient,
+      connectedAgents: agentBridgeClients.size,
+      pendingRequests: pendingBridgeRequests.size,
+      supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+    });
+  });
+
+  app.post('/set-project', (req, res) => {
+    const { path: inputPath } = req.body;
+    if (!inputPath) return res.status(400).json({ error: 'path required' });
+    const resolved = resolveWritableProjectPath(inputPath);
+    if (!fs.existsSync(resolved)) {
+      return res.status(400).json({ error: `Path does not exist: ${resolved}` });
+    }
+    projectPath = setSavedProjectPath(resolved);
+    logger.info(`✅ Project path set: ${projectPath}`);
+    res.json({ ok: true, projectPath });
+  });
+
+  app.post('/write', (req, res) => {
+    const { code, structName, images, customPath } = req.body;
+
+    const target = customPath ? resolveWritableProjectPath(customPath) : projectPath;
+
+    if (!target) {
+      return res.status(400).json({
+        error: 'No project path set. Pass --project /path/to/MyApp when starting the MCP server, or set it from the plugin UI/MCP.',
+      });
+    }
+
+    if (!fs.existsSync(target)) {
+      return res.status(400).json({ error: `Project path does not exist: ${target}` });
+    }
+
+    projectPath = target;
+    if (customPath && path.resolve(customPath) !== target) {
+      logger.info(`📍 Resolved project path: ${path.resolve(customPath)} → ${target}`);
+    }
+
+    projectPath = setSavedProjectPath(target);
+    const writeResult = writeSwiftUIScreen({
+      targetDir: target,
+      code,
+      structName,
+      images: Array.isArray(images) ? images : [],
+    });
+
+    if (!writeResult.ok) {
+      return res.status(207).json({
+        ok: false,
+        results: writeResult.results,
+        projectPath: writeResult.projectPath,
+        generatedRoot: writeResult.generatedRoot,
+        layoutVersion: GENERATED_LAYOUT_VERSION,
+      });
+    }
+
+    res.json({
+      ok: true,
+      results: writeResult.results,
+      projectPath: writeResult.projectPath,
+      generatedRoot: writeResult.generatedRoot,
+      layoutVersion: GENERATED_LAYOUT_VERSION,
+    });
+  });
+
+  app.post('/choose-project', (req, res) => {
+    if (process.platform !== 'darwin') {
+      return res.status(501).json({
+        error: 'Native project folder chooser is only implemented for macOS. Enter the path manually in the plugin UI or set it from MCP.',
+      });
+    }
+
+    const script = [
+      'set chosenFolder to choose folder with prompt "Select the Xcode project source folder"',
+      'POSIX path of chosenFolder',
+    ];
+
+    execFile('osascript', script.flatMap((line) => ['-e', line]), (err, stdout, stderr) => {
+      if (err) {
+        const details = `${stderr || ''} ${err.message || ''}`.trim();
+        if (details.includes('User canceled') || details.includes('(-128)')) {
+          return res.json({ ok: false, canceled: true });
+        }
+
+        return res.status(500).json({
+          error: `Failed to choose a project folder: ${details || 'Unknown error'}`,
+        });
+      }
+
+      const resolved = path.resolve(stdout.trim());
+      const writeTarget = resolveWritableProjectPath(resolved);
+      if (!fs.existsSync(writeTarget)) {
+        return res.status(400).json({ error: `Chosen path does not exist: ${writeTarget}` });
+      }
+
+      projectPath = setSavedProjectPath(writeTarget);
+      logger.info(`✅ Project path set: ${projectPath}`);
+      res.json({ ok: true, projectPath });
+    });
+  });
+
+  // GET /design-context — returns current selection's design context as JSON.
+  // Lets any AI tool (Windsurf, a script, a browser) fetch the live Figma context
+  // via a simple HTTP GET without needing MCP protocol or copy-paste.
+  // Usage: GET http://localhost:7765/design-context?maxDepth=4
+  app.get('/design-context', async (req, res) => {
+    if (!pluginBridgeClient || pluginBridgeClient.readyState !== WebSocket.OPEN) {
+      return res.status(503).json({
+        ok: false,
+        error: 'No Figma plugin is connected to the bridge. Open the plugin in Figma first.',
+        hint: 'npx @createlex/figma-swiftui-mcp start --project ./MyApp',
+      });
+    }
+
+    const maxDepth = Math.min(parseInt(req.query.maxDepth, 10) || 4, 8);
+    const requestId = `http-ctx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const response = await new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        pendingBridgeRequests.delete(requestId);
+        resolve({ ok: false, error: 'Timed out waiting for design context from plugin' });
+      }, 20000);
+
+      pendingBridgeRequests.set(requestId, {
+        origin: null,
+        action: 'get_design_context',
+        resolveCallback: (msg) => {
+          clearTimeout(timeout);
+          resolve(msg);
+        },
+      });
+
+      sendBridgeMessage(pluginBridgeClient, {
+        type: 'bridge-request',
+        requestId,
+        action: 'get_design_context',
+        params: { maxDepth, includeScreenshot: false },
+        protocolVersion: BRIDGE_PROTOCOL_VERSION,
+        timestamp: new Date().toISOString(),
+      });
+      broadcastBridgeStatus();
+    });
+
+    if (!response.ok) {
+      return res.status(502).json({ ok: false, error: response.error || 'Plugin returned an error' });
+    }
+
+    const data = response.data || {};
+
+    // Build the full generation prompt so AI tools without MCP access
+    // can still generate proper native SwiftUI with individual elements.
+    let generationPrompt = null;
+    try {
+      generationPrompt = buildGenerationPrompt(data);
+    } catch (_) {
+      // Non-fatal — prompt is a bonus, not required
+    }
+
+    const assetCount = data.assetExportPlan?.candidates?.length ?? 0;
+    const aiWorkflow = {
+      IF_YOU_HAVE_MCP_ACCESS: {
+        step1: 'Call the MCP tool `write_selection_to_xcode` with generationMode="editable" (the default). It exports individual PNG assets with correct blendMode info and generates Image("name").blendMode() calls automatically.',
+        step2: 'After write_selection_to_xcode returns, ONLY refine: add GeometryReader for responsiveness, wire @State interactions. DO NOT rewrite Image("name") calls, DO NOT switch to fidelity mode unless the whole frame is a single photo with no text.',
+        mcpTool: 'write_selection_to_xcode',
+        mcpServer: 'figma-swiftui',
+      },
+      IF_NO_MCP_ACCESS: {
+        instruction: 'Use _generationPrompt.systemPrompt as the system message and _generationPrompt.userMessage as the user message to generate native SwiftUI code. Output individual SwiftUI views — Text(), VStack, HStack, ZStack, Image("name") — NOT a single composite Image().',
+        rule1: 'Every asset in assetExportPlan.candidates MUST become Image("assetName").resizable() — never Rectangle() or Color.',
+        rule2: 'Text nodes become Text("content") with .font(.system(size: X, weight: .bold)) — NEVER custom font names.',
+        rule3: 'Output a full SwiftUI View struct with individual elements positioned using the node geometry in the design context.',
+        rule4: 'End with #Preview { StructName() }.',
+      },
+      assetCandidateCount: assetCount,
+      warning: 'DO NOT generate a single Image() wrapping the whole frame. Generate individual SwiftUI elements for each node.',
+    };
+
+    res.json({ ok: true, ...data, _generationPrompt: generationPrompt, _aiWorkflow: aiWorkflow });
+  });
+
+  function sendBridgeMessage(ws, payload) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+
+    ws.send(JSON.stringify(payload));
+    return true;
+  }
+
+  function broadcastBridgeStatus() {
+    const payload = {
+      type: 'bridge-status',
+      protocolVersion: BRIDGE_PROTOCOL_VERSION,
+      pluginConnected: !!pluginBridgeClient,
+      connectedAgents: agentBridgeClients.size,
+      pendingRequests: pendingBridgeRequests.size,
+      supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+      timestamp: new Date().toISOString(),
+    };
+
+    if (pluginBridgeClient) {
+      sendBridgeMessage(pluginBridgeClient, payload);
+    }
+
+    for (const client of agentBridgeClients) {
+      sendBridgeMessage(client, payload);
+    }
+
+    for (const client of passivePluginClients) {
+      sendBridgeMessage(client, payload);
+    }
+  }
+
+  function releasePendingRequestsForSocket(socket, reason) {
+    for (const [requestId, pending] of pendingBridgeRequests.entries()) {
+      if (pending.origin !== socket) {
+        continue;
+      }
+
+      pendingBridgeRequests.delete(requestId);
+      sendBridgeMessage(socket, {
+        type: 'bridge-response',
+        requestId,
+        action: pending.action,
+        ok: false,
+        error: reason,
+        protocolVersion: BRIDGE_PROTOCOL_VERSION,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  function failAllPendingBridgeRequests(reason) {
+    for (const [requestId, pending] of pendingBridgeRequests.entries()) {
+      sendBridgeMessage(pending.origin, {
+        type: 'bridge-response',
+        requestId,
+        action: pending.action,
+        ok: false,
+        error: reason,
+        protocolVersion: BRIDGE_PROTOCOL_VERSION,
+        timestamp: new Date().toISOString(),
+      });
+      pendingBridgeRequests.delete(requestId);
+    }
+  }
+
+  function attachBridgeRole(socket, role) {
+    socket.bridgeRole = role;
+
+    if (role === 'plugin-ui') {
+      if (pluginBridgeClient && pluginBridgeClient !== socket && pluginBridgeClient.readyState === WebSocket.OPEN) {
+        socket.bridgeRole = 'plugin-ui-passive';
+        agentBridgeClients.delete(socket);
+        passivePluginClients.add(socket);
+
+        sendBridgeMessage(socket, {
+          type: 'hello-ack',
+          role: 'plugin-ui-passive',
+          accepted: false,
+          reason: 'Another Figma plugin window is already attached to the bridge',
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          pluginConnected: true,
+          supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+          timestamp: new Date().toISOString(),
+        });
+        broadcastBridgeStatus();
+        return false;
+      }
+
+      pluginBridgeClient = socket;
+      passivePluginClients.delete(socket);
+      agentBridgeClients.delete(socket);
+    } else {
+      passivePluginClients.delete(socket);
+      agentBridgeClients.add(socket);
+      if (pluginBridgeClient === socket) {
+        pluginBridgeClient = null;
+      }
+    }
+
+    broadcastBridgeStatus();
+    return true;
+  }
+
+  function demoteActivePlugin(reason = 'Another Figma plugin window took the bridge') {
+    if (!pluginBridgeClient || pluginBridgeClient.readyState !== WebSocket.OPEN) {
+      pluginBridgeClient = null;
+      return;
+    }
+
+    const previous = pluginBridgeClient;
+    pluginBridgeClient = null;
+    previous.bridgeRole = 'plugin-ui-passive';
+    passivePluginClients.add(previous);
+
+    sendBridgeMessage(previous, {
+      type: 'hello-ack',
+      role: 'plugin-ui-passive',
+      accepted: false,
+      reason,
+      protocolVersion: BRIDGE_PROTOCOL_VERSION,
+      pluginConnected: true,
+      supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  const bridgeWss = new WebSocketServer({ server, path: '/bridge' });
+
+  bridgeWss.on('error', (error) => {
+    if (error && error.code === 'EADDRINUSE') {
+      return;
+    }
+    logger.error('[figma-swiftui-bridge] WebSocket server error:', error);
+  });
+
+  bridgeWss.on('connection', (socket) => {
+    socket.bridgeRole = 'agent';
+    agentBridgeClients.add(socket);
+
+    sendBridgeMessage(socket, {
+      type: 'bridge-status',
+      protocolVersion: BRIDGE_PROTOCOL_VERSION,
+      pluginConnected: !!pluginBridgeClient,
+      connectedAgents: agentBridgeClients.size,
+      pendingRequests: pendingBridgeRequests.size,
+      supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+      timestamp: new Date().toISOString(),
+    });
+
+    socket.on('message', (rawMessage) => {
+      let message;
+
+      try {
+        message = JSON.parse(rawMessage.toString());
+      } catch (err) {
+        sendBridgeMessage(socket, {
+          type: 'bridge-error',
+          error: 'Invalid JSON message',
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          timestamp: new Date().toISOString(),
+        });
+        return;
+      }
+
+      if (message.type === 'hello') {
+        if (message.role === 'plugin-ui' && message.takeover === true) {
+          demoteActivePlugin('Another Figma plugin window took the bridge');
+        }
+
+        const attached = attachBridgeRole(socket, message.role === 'plugin-ui' ? 'plugin-ui' : 'agent');
+        if (attached === false) {
+          return;
+        }
+        sendBridgeMessage(socket, {
+          type: 'hello-ack',
+          role: socket.bridgeRole,
+          accepted: true,
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          pluginConnected: !!pluginBridgeClient,
+          supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+          timestamp: new Date().toISOString(),
+        });
+        return;
+      }
+
+      if (message.type === 'bridge-control') {
+        if (message.action === 'takeover-plugin-ui') {
+          if (socket.bridgeRole !== 'plugin-ui-passive') {
+            sendBridgeMessage(socket, {
+              type: 'bridge-error',
+              error: 'Only a passive Figma plugin window can request takeover',
+              protocolVersion: BRIDGE_PROTOCOL_VERSION,
+              timestamp: new Date().toISOString(),
+            });
+            return;
+          }
+
+          demoteActivePlugin('Another Figma plugin window took the bridge');
+          passivePluginClients.delete(socket);
+          pluginBridgeClient = socket;
+          socket.bridgeRole = 'plugin-ui';
+          sendBridgeMessage(socket, {
+            type: 'hello-ack',
+            role: 'plugin-ui',
+            accepted: true,
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            pluginConnected: true,
+            supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+            timestamp: new Date().toISOString(),
+          });
+          broadcastBridgeStatus();
+          return;
+        }
+
+        sendBridgeMessage(socket, {
+          type: 'bridge-error',
+          error: `Unsupported bridge control action: ${message.action || 'unknown'}`,
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          timestamp: new Date().toISOString(),
+        });
+        return;
+      }
+
+      if (message.type === 'bridge-request') {
+        const requestId = typeof message.requestId === 'string' && message.requestId
+          ? message.requestId
+          : `bridge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+        if (!pluginBridgeClient || pluginBridgeClient.readyState !== WebSocket.OPEN) {
+          sendBridgeMessage(socket, {
+            type: 'bridge-response',
+            requestId,
+            action: message.action || 'unknown',
+            ok: false,
+            error: 'No plugin session is connected to the bridge',
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            timestamp: new Date().toISOString(),
+          });
+          return;
+        }
+
+        pendingBridgeRequests.set(requestId, {
+          origin: socket,
+          action: message.action || 'unknown',
+        });
+
+        sendBridgeMessage(pluginBridgeClient, {
+          type: 'bridge-request',
+          requestId,
+          action: message.action,
+          params: message.params || {},
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          timestamp: new Date().toISOString(),
+        });
+        broadcastBridgeStatus();
+        return;
+      }
+
+      if (message.type === 'bridge-response') {
+        const pending = pendingBridgeRequests.get(message.requestId);
+        if (!pending) {
+          return;
+        }
+
+        pendingBridgeRequests.delete(message.requestId);
+        if (typeof pending.resolveCallback === 'function') {
+          pending.resolveCallback(message);
+        } else {
+          sendBridgeMessage(pending.origin, {
+            ...message,
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            timestamp: new Date().toISOString(),
+          });
+        }
+        broadcastBridgeStatus();
+        return;
+      }
+
+      if (message.type === 'bridge-event') {
+        const payload = {
+          ...message,
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          timestamp: message.timestamp || new Date().toISOString(),
+        };
+
+        for (const client of agentBridgeClients) {
+          if (client !== socket) {
+            sendBridgeMessage(client, payload);
+          }
+        }
+        return;
+      }
+
+      sendBridgeMessage(socket, {
+        type: 'bridge-error',
+        error: `Unsupported bridge message type: ${message.type || 'unknown'}`,
+        protocolVersion: BRIDGE_PROTOCOL_VERSION,
+        timestamp: new Date().toISOString(),
+      });
+    });
+
+    socket.on('close', () => {
+      if (pluginBridgeClient === socket) {
+        pluginBridgeClient = null;
+        failAllPendingBridgeRequests('Plugin session disconnected from bridge');
+        const nextPlugin = Array.from(passivePluginClients).find((client) => client.readyState === WebSocket.OPEN) || null;
+        if (nextPlugin) {
+          passivePluginClients.delete(nextPlugin);
+          pluginBridgeClient = nextPlugin;
+          nextPlugin.bridgeRole = 'plugin-ui';
+          sendBridgeMessage(nextPlugin, {
+            type: 'hello-ack',
+            role: 'plugin-ui',
+            accepted: true,
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            pluginConnected: true,
+            supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+            timestamp: new Date().toISOString(),
+          });
+        }
+      } else if (passivePluginClients.has(socket)) {
+        passivePluginClients.delete(socket);
+      } else {
+        agentBridgeClients.delete(socket);
+        releasePendingRequestsForSocket(socket, 'Agent disconnected from bridge');
+      }
+
+      broadcastBridgeStatus();
+    });
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', async (error) => {
+      if (error && error.code === 'EADDRINUSE') {
+        try {
+          const running = await waitForExistingBridge({ host, port });
+          logger.warn(`ℹ️  Using existing healthy bridge at http://${host}:${port}`);
+          resolve({
+            app,
+            server: null,
+            bridgeWss: null,
+            port,
+            host,
+            alreadyRunning: true,
+            projectPath,
+            bridgeInfo: running.info,
+            getProjectPath: () => projectPath,
+            getBridgeInfo: () => running.info,
+          });
+          return;
+        } catch (existingError) {
+          // Existing bridge is unhealthy — kill stale processes and start fresh
+          logger.warn(`⚠️  ${existingError.message}`);
+          try {
+            await killStaleAndRetry({ host, port, logger });
+            // Re-attempt listen after killing stale processes
+            server.listen(port, host, () => {
+              logger.info(`🚀 Figma SwiftUI bridge running at http://${host}:${port} (recovered from stale)`);
+              if (projectPath) {
+                logger.info(`📂 Project path: ${projectPath}`);
+              }
+              logger.info(`🌉 Bridge ready at ws://${host}:${port}/bridge`);
+              resolve({
+                app,
+                server,
+                bridgeWss,
+                port,
+                host,
+                alreadyRunning: false,
+                getProjectPath: () => projectPath,
+                setAuthRequired,
+                getBridgeInfo: () => ({
+                  protocolVersion: BRIDGE_PROTOCOL_VERSION,
+                  pluginConnected: !!pluginBridgeClient,
+                  connectedAgents: agentBridgeClients.size,
+                  pendingRequests: pendingBridgeRequests.size,
+                  supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+                }),
+                close: () => new Promise((closeResolve, closeReject) => {
+                  bridgeWss.close(() => {
+                    server.close((closeError) => {
+                      if (closeError) closeReject(closeError);
+                      else closeResolve();
+                    });
+                  });
+                }),
+              });
+            });
+            return;
+          } catch (retryError) {
+            reject(new Error(`Failed to recover bridge: ${retryError.message}`));
+            return;
+          }
+        }
+      }
+
+      reject(error);
+    });
+
+    server.listen(port, host, () => {
+      logger.info(`🚀 Figma SwiftUI bridge running at http://${host}:${port}`);
+      if (projectPath) {
+        logger.info(`📂 Project path: ${projectPath}`);
+      } else {
+        logger.warn('⚠️  No project path set. Use --project /path/to/MyApp/MyApp or set it from MCP/plugin UI.');
+      }
+      logger.info(`🌉 Bridge ready at ws://${host}:${port}/bridge`);
+
+      resolve({
+        app,
+        server,
+        bridgeWss,
+        port,
+        host,
+        alreadyRunning: false,
+        getProjectPath: () => projectPath,
+        setAuthRequired,
+        getBridgeInfo: () => ({
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          pluginConnected: !!pluginBridgeClient,
+          connectedAgents: agentBridgeClients.size,
+          pendingRequests: pendingBridgeRequests.size,
+          supportedActions: SUPPORTED_BRIDGE_ACTIONS,
+        }),
+        close: () => new Promise((closeResolve, closeReject) => {
+          bridgeWss.close(() => {
+            server.close((closeError) => {
+              if (closeError) {
+                closeReject(closeError);
+              } else {
+                closeResolve();
+              }
+            });
+          });
+        }),
+      });
+    });
+  });
+}
+
+module.exports = {
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  BRIDGE_PROTOCOL_VERSION,
+  SUPPORTED_BRIDGE_ACTIONS,
+  startBridgeServer,
+};