npm - kiro-mobile-bridge - Versions diffs - 1.0.13 → 1.0.15 - Mend

kiro-mobile-bridge 1.0.13 → 1.0.15

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 (7) hide show

package/README.md +3 -8
package/package.json +1 -1
package/src/public/index.html +52 -14
package/src/routes/api.js +104 -4
package/src/services/cdp.js +15 -1
package/src/services/snapshot.js +123 -18
package/src/utils/network.js +63 -16

package/README.md CHANGED Viewed

@@ -2,7 +2,7 @@
 A lightweight mobile interface that lets you monitor and control Kiro IDE agent sessions from your phone over LAN, with a live preview of chat, tasks, and code via Chrome DevTools Protocol.
-<img width="1829" height="1065" alt="Untitled design (2)" src="https://github.com/user-attachments/assets/6f55e527-7e66-46b6-b0fe-c2a5a527dec4" />
+<img width="1829" height="1065" alt="Untitled design (4)" src="https://github.com/user-attachments/assets/d548c43b-4501-4d66-aed7-ad021a44f9cb" />
 ## Features
@@ -24,14 +24,9 @@ A lightweight mobile interface that lets you monitor and control Kiro IDE agent
 Start Kiro with the remote debugging port enabled:
-**Run Kiro with debugging port:**
+**Run Kiro with debugging port on terminal:**
 ```bash
-# Windows (from default install location)
-"%LOCALAPPDATA%\Programs\Kiro\Kiro.exe" --remote-debugging-port=9000
-# macOS
-/Applications/Kiro.app/Contents/MacOS/Kiro --remote-debugging-port=9000
-# Linux (installed)
-/opt/Kiro/kiro --remote-debugging-port=9000
+kiro --remote-debugging-port=9000
 ```
 ### 2. Run with npx (Recommended)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "kiro-mobile-bridge",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "A simple mobile web interface for monitoring Kiro IDE agent sessions from your phone over LAN",
   "type": "module",
   "main": "src/server.js",

package/src/public/index.html CHANGED Viewed

@@ -214,9 +214,10 @@
     .empty-state p { font-size: 14px; max-width: 280px; }
     /* =============================================================================
-       Mobile Bridge Customizations - Hide Follow and Revert buttons in snackbar
+       Mobile Bridge Customizations - Hide Follow button in snackbar (keep "Looks good to me")
        ============================================================================= */
-    .kiro-snackbar-actions .kiro-button[data-variant="primary"] { display: none !important; }
+    /* Hide only the Follow button by targeting buttons containing "Follow" text - done via JS */
+    /* Note: "Looks good to me" and other action buttons should remain visible */
   </style>
 </head>
 <body>
@@ -1083,10 +1084,11 @@
     }
     function hideRevertButton() {
-      // Hide Revert button by finding buttons with "Revert" text in snackbar
+      // Hide Revert and Follow buttons by finding buttons with specific text in snackbar
+      // Note: "Looks good to me" and other action buttons should remain visible
       panels.chat.content.querySelectorAll('.kiro-snackbar button, .kiro-snackbar-actions button').forEach(btn => {
         const text = (btn.textContent || '').trim().toLowerCase();
-        if (text === 'revert') {
+        if (text === 'revert' || text === 'follow') {
           btn.style.display = 'none';
         }
       });
@@ -1147,15 +1149,19 @@
         const lines = data.content.split('\n');
         let html = '';
+        // Show info banner for partial content
         if (data.isPartial || data.note) {
-          html += `<div style="padding: 8px 12px; background: #2d2d30; color: #888; font-size: 11px; border-bottom: 1px solid #3c3c3c;">
-            <span class="codicon codicon-info" style="margin-right: 6px;"></span>${data.note || 'Showing visible lines only.'}
+          const noteText = data.note || 'Showing visible lines only. Use Explorer to open full file.';
+          html += `<div style="padding: 10px 12px; background: linear-gradient(135deg, #2d2d30 0%, #252526 100%); color: #a78bfa; font-size: 12px; border-bottom: 1px solid #3c3c3c; display: flex; align-items: center; gap: 8px;">
+            <span class="codicon codicon-warning" style="color: #f0b429;"></span>
+            <span>${noteText}</span>
           </div>`;
         }
         html += '<pre class="editor-code">';
         const startLineNum = data.startLine || 1;
         let startIdx = 0;
+        // Skip leading empty lines (max 3)
         while (startIdx < lines.length && lines[startIdx].trim() === '' && startIdx < 3) startIdx++;
         lines.slice(startIdx).forEach((line, idx) => {
@@ -1165,9 +1171,17 @@
         });
         html += '</pre>';
+        // Footer with line info
         const endLine = startLineNum + startIdx + lines.slice(startIdx).length - 1;
+        const lineInfo = data.lineCount
+          ? `Lines ${startLineNum}-${endLine} of ${data.lineCount}`
+          : `Lines ${startLineNum}-${endLine}`;
+        const fullFileIndicator = !data.isPartial && data.lineCount && endLine >= data.lineCount
+          ? ' <span style="color: #4caf50;">✓ Complete file</span>'
+          : '';
         html += `<div style="padding: 6px 12px; background: #252526; color: #666; font-size: 11px; border-top: 1px solid #3c3c3c;">
-          Lines ${startLineNum}-${endLine}${data.lineCount ? ` of ${data.lineCount}` : ''}
+          ${lineInfo}${fullFileIndicator}
         </div>`;
         panels.editor.content.innerHTML = html;
@@ -2032,7 +2046,21 @@
     async function openFileInEditor(filePath) {
       if (!selectedCascadeId || !filePath) return;
-      showToast(`Opening ${filePath}...`, 1500);
+      // Clean the file path - remove extra whitespace, quotes, backticks, and common prefixes
+      let cleanPath = filePath.trim()
+        .replace(/^['"`]+|['"`]+$/g, '')  // Remove surrounding quotes
+        .replace(/^\s*#\s*/, '')           // Remove markdown header prefix
+        .replace(/^\s*[-*]\s*/, '')        // Remove list markers
+        .replace(/\s+/g, ' ')              // Normalize whitespace
+        .trim();
+      // Extract just the file path if it contains extra text (e.g., "file.ts - some description")
+      const pathMatch = cleanPath.match(/^([^\s]+\.(ts|tsx|js|jsx|py|java|html|css|json|md|yaml|yml|xml|sql|go|rs|c|cpp|h|cs|rb|php|sh|vue|svelte))/i);
+      if (pathMatch) {
+        cleanPath = pathMatch[1];
+      }
+      showToast(`Opening ${cleanPath}...`, 1500);
       // Switch to Editor tab
       const editorTab = document.querySelector('[data-panel="editor"]');
@@ -2050,25 +2078,30 @@
         const readResult = await fetch(`/readFile/${selectedCascadeId}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ filePath })
+          body: JSON.stringify({ filePath: cleanPath })
         });
         if (readResult.ok) {
           const data = await readResult.json();
           if (data.content) {
             renderEditorSnapshot(data);
-            showToast(`Opened ${data.fileName || filePath}`, 1500, true);
+            showToast(`Opened ${data.fileName || cleanPath}`, 1500, true);
             return;
           }
+        } else {
+          // Log the error for debugging
+          const errorData = await readResult.json().catch(() => ({}));
+          console.log('[OpenFile] Direct read failed:', errorData.error || readResult.status);
         }
-        // Fallback: Click file link in Kiro
+        // Fallback: Click file link in Kiro to open it there
         await fetch(`/click/${selectedCascadeId}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ tag: 'a', text: filePath, isFileLink: true, filePath })
+          body: JSON.stringify({ tag: 'a', text: cleanPath, isFileLink: true, filePath: cleanPath })
         });
+        // Wait for Kiro to open the file
         await new Promise(resolve => setTimeout(resolve, 800));
         const fetchEditor = async () => {
@@ -2076,7 +2109,11 @@
             const r = await fetch(`/editor/${selectedCascadeId}`);
             if (r.ok) {
               const data = await r.json();
-              if (data.content || data.html) { renderEditorSnapshot(data); showToast(`Opened ${data.fileName || filePath}`, 1500, true); return true; }
+              if (data.content || data.html) {
+                renderEditorSnapshot(data);
+                showToast(`Opened ${data.fileName || cleanPath}`, 1500, true);
+                return true;
+              }
             }
           } catch (e) {}
           return false;
@@ -2085,10 +2122,11 @@
         if (!await fetchEditor()) {
           await new Promise(resolve => setTimeout(resolve, 500));
           if (!await fetchEditor()) {
-            showEmptyState('editor', 'codicon-file-code', `Could not load ${filePath}.`);
+            showEmptyState('editor', 'codicon-file-code', `Could not load ${cleanPath}. Try opening it in Kiro first.`);
           }
         }
       } catch (e) {
+        console.error('[OpenFile] Error:', e);
         showToast('Failed to open file');
         showEmptyState('editor', 'codicon-file-code', 'Failed to load file.');
       }

package/src/routes/api.js CHANGED Viewed

@@ -215,6 +215,7 @@ export function createApiRouter(cascades, mainWindowCDP) {
     try {
       // Get workspace root
       const workspaceRoot = await getWorkspaceRoot(mainWindowCDP) || process.cwd();
+      console.log(`[ReadFile] Workspace root: ${workspaceRoot}`);
       // SECURITY: Validate path is within workspace root
       const pathValidation = validatePathWithinRoot(sanitizedPath, workspaceRoot);
@@ -222,19 +223,46 @@ export function createApiRouter(cascades, mainWindowCDP) {
       let content = null;
       let foundPath = null;
+      // Try 1: Direct path validation
       if (pathValidation.valid) {
-        // Try the validated path first
         try {
           content = await fs.readFile(pathValidation.resolvedPath, 'utf-8');
           foundPath = pathValidation.resolvedPath;
+          console.log(`[ReadFile] Found at validated path: ${foundPath}`);
         } catch (e) {
-          // File doesn't exist at validated path, try searching
+          // File doesn't exist at validated path, try other methods
         }
       }
-      // If not found, search within workspace only
+      // Try 2: Common path variations
+      if (!content) {
+        const pathVariations = [
+          sanitizedPath,
+          sanitizedPath.replace(/^\.\//, ''),  // Remove leading ./
+          sanitizedPath.replace(/^\//, ''),     // Remove leading /
+          `src/${sanitizedPath}`,               // Try in src/
+          `src/${sanitizedPath.replace(/^src\//, '')}`,
+        ];
+        for (const variation of pathVariations) {
+          const varValidation = validatePathWithinRoot(variation, workspaceRoot);
+          if (varValidation.valid) {
+            try {
+              content = await fs.readFile(varValidation.resolvedPath, 'utf-8');
+              foundPath = varValidation.resolvedPath;
+              console.log(`[ReadFile] Found at variation: ${foundPath}`);
+              break;
+            } catch (e) {
+              // Continue to next variation
+            }
+          }
+        }
+      }
+      // Try 3: Search by filename within workspace
       if (!content) {
         const fileName = path.basename(sanitizedPath);
+        console.log(`[ReadFile] Searching for filename: ${fileName}`);
         foundPath = await findFileRecursive(workspaceRoot, fileName, MAX_FILE_SEARCH_DEPTH);
         if (foundPath) {
@@ -242,6 +270,7 @@ export function createApiRouter(cascades, mainWindowCDP) {
           const foundValidation = validatePathWithinRoot(foundPath, workspaceRoot);
           if (foundValidation.valid) {
             content = await fs.readFile(foundPath, 'utf-8');
+            console.log(`[ReadFile] Found via search: ${foundPath}`);
           } else {
             console.warn(`[ReadFile] Found file outside workspace: ${foundPath}`);
             foundPath = null;
@@ -249,7 +278,28 @@ export function createApiRouter(cascades, mainWindowCDP) {
         }
       }
+      // Try 4: Search with partial path matching
+      if (!content && sanitizedPath.includes('/')) {
+        const pathParts = sanitizedPath.split('/');
+        const fileName = pathParts[pathParts.length - 1];
+        const parentDir = pathParts[pathParts.length - 2];
+        if (parentDir && fileName) {
+          console.log(`[ReadFile] Searching for ${parentDir}/${fileName}`);
+          foundPath = await findFileWithParent(workspaceRoot, parentDir, fileName, MAX_FILE_SEARCH_DEPTH);
+          if (foundPath) {
+            const foundValidation = validatePathWithinRoot(foundPath, workspaceRoot);
+            if (foundValidation.valid) {
+              content = await fs.readFile(foundPath, 'utf-8');
+              console.log(`[ReadFile] Found via parent search: ${foundPath}`);
+            }
+          }
+        }
+      }
       if (!content) {
+        console.log(`[ReadFile] File not found: ${sanitizedPath}`);
         return res.status(404).json({ error: 'File not found within workspace' });
       }
@@ -257,7 +307,7 @@ export function createApiRouter(cascades, mainWindowCDP) {
       res.json({
         content,
-        fileName: path.basename(sanitizedPath),
+        fileName: path.basename(foundPath || sanitizedPath),
         fullPath: foundPath,
         language,
         lineCount: content.split('\n').length,
@@ -489,6 +539,56 @@ async function findFileRecursive(dir, fileName, maxDepth = MAX_FILE_SEARCH_DEPTH
   return null;
 }
+/**
+ * Find file with matching parent directory name
+ * Useful when path is like "services/snapshot.js" and we need to find the right one
+ * @param {string} dir - Directory to search
+ * @param {string} parentDirName - Expected parent directory name
+ * @param {string} fileName - File name to find
+ * @param {number} maxDepth - Maximum search depth
+ * @param {number} currentDepth - Current depth (internal)
+ * @returns {Promise<string|null>}
+ */
+async function findFileWithParent(dir, parentDirName, fileName, maxDepth = MAX_FILE_SEARCH_DEPTH, currentDepth = 0) {
+  if (currentDepth > maxDepth) return null;
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    // Check if current directory matches parent name and contains the file
+    const currentDirName = path.basename(dir);
+    if (currentDirName === parentDirName) {
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name === fileName) {
+          return path.join(dir, entry.name);
+        }
+      }
+    }
+    // Recurse into directories
+    for (const entry of entries) {
+      if (entry.isDirectory() &&
+          (!entry.name.startsWith('.') || entry.name === '.kiro') &&
+          entry.name !== 'node_modules' &&
+          entry.name !== 'dist' &&
+          entry.name !== 'build' &&
+          entry.name !== '.git') {
+        const found = await findFileWithParent(
+          path.join(dir, entry.name),
+          parentDirName,
+          fileName,
+          maxDepth,
+          currentDepth + 1
+        );
+        if (found) return found;
+      }
+    }
+  } catch (e) {
+    // Directory not accessible, skip
+  }
+  return null;
+}
 /**
  * Collect workspace files for file tree
  * @param {string} workspaceRoot - Workspace root directory

package/src/services/cdp.js CHANGED Viewed

@@ -7,13 +7,27 @@ import { CDP_CALL_TIMEOUT, HTTP_TIMEOUT } from '../utils/constants.js';
 /**
  * Fetch JSON from a CDP endpoint
+ * Tries both 127.0.0.1 and localhost for cross-platform compatibility
  * @param {number} port - The port to fetch from
  * @param {string} path - The path to fetch (default: /json/list)
  * @returns {Promise<any>} - Parsed JSON response
  */
 export function fetchCDPTargets(port, path = '/json/list') {
+  // Try 127.0.0.1 first, then localhost as fallback
+  return fetchFromHost('127.0.0.1', port, path)
+    .catch(() => fetchFromHost('localhost', port, path));
+}
+/**
+ * Fetch JSON from a specific host
+ * @param {string} host - The host to connect to
+ * @param {number} port - The port to fetch from
+ * @param {string} path - The path to fetch
+ * @returns {Promise<any>} - Parsed JSON response
+ */
+function fetchFromHost(host, port, path) {
   return new Promise((resolve, reject) => {
-    const url = `http://127.0.0.1:${port}${path}`;
+    const url = `http://${host}:${port}${path}`;
     const req = http.get(url, { timeout: HTTP_TIMEOUT }, (res) => {
       let data = '';

package/src/services/snapshot.js CHANGED Viewed

@@ -285,28 +285,96 @@ export async function captureEditor(cdp) {
       }
     }
-    // Try Monaco API
+    // Method 1: Try VS Code/Kiro API (acquireVsCodeApi or global vscode)
     try {
-      const monacoEditors = targetDoc.querySelectorAll('.monaco-editor');
-      for (const editorEl of monacoEditors) {
-        const editorInstance = editorEl.__vscode_editor__ || editorEl._editor ||
-          (window.monaco && window.monaco.editor && window.monaco.editor.getEditors && window.monaco.editor.getEditors()[0]);
-        if (editorInstance && editorInstance.getModel) {
-          const model = editorInstance.getModel();
-          if (model) {
+      // Check for VS Code webview API
+      if (typeof acquireVsCodeApi === 'function') {
+        const vscode = acquireVsCodeApi();
+        if (vscode && vscode.getState) {
+          const state = vscode.getState();
+          if (state && state.content) {
+            result.content = state.content;
+            result.lineCount = state.content.split('\\n').length;
+            result.hasContent = true;
+          }
+        }
+      }
+    } catch(e) {
+      // VS Code API not available
+    }
+    // Method 2: Try Monaco API with multiple access patterns
+    if (!result.content) {
+      try {
+        const monacoEditors = targetDoc.querySelectorAll('.monaco-editor');
+        for (const editorEl of monacoEditors) {
+          // Try various ways to access the editor instance
+          let editorInstance = null;
+          // Direct property access
+          editorInstance = editorEl.__vscode_editor__ || editorEl._editor;
+          // Try global monaco
+          if (!editorInstance && window.monaco && window.monaco.editor) {
+            const editors = window.monaco.editor.getEditors ? window.monaco.editor.getEditors() : [];
+            if (editors.length > 0) editorInstance = editors[0];
+          }
+          // Try to find editor via data attributes or parent elements
+          if (!editorInstance) {
+            const editorContainer = editorEl.closest('[data-uri]') || editorEl.closest('.editor-instance');
+            if (editorContainer && editorContainer._editor) {
+              editorInstance = editorContainer._editor;
+            }
+          }
+          if (editorInstance && editorInstance.getModel) {
+            const model = editorInstance.getModel();
+            if (model) {
+              result.content = model.getValue();
+              result.lineCount = model.getLineCount();
+              result.language = model.getLanguageId ? model.getLanguageId() : '';
+              result.hasContent = true;
+              break;
+            }
+          }
+        }
+      } catch(e) {
+        // Monaco API not available, continue
+      }
+    }
+    // Method 3: Try to get content from Monaco's internal model store
+    if (!result.content) {
+      try {
+        if (window.monaco && window.monaco.editor) {
+          const models = window.monaco.editor.getModels ? window.monaco.editor.getModels() : [];
+          // Find the model that matches the active file
+          for (const model of models) {
+            const uri = model.uri ? model.uri.toString() : '';
+            if (result.fileName && uri.includes(result.fileName)) {
+              result.content = model.getValue();
+              result.lineCount = model.getLineCount();
+              result.language = model.getLanguageId ? model.getLanguageId() : '';
+              result.hasContent = true;
+              break;
+            }
+          }
+          // If no match by filename, use the first model with content
+          if (!result.content && models.length > 0) {
+            const model = models[0];
             result.content = model.getValue();
             result.lineCount = model.getLineCount();
             result.language = model.getLanguageId ? model.getLanguageId() : '';
             result.hasContent = true;
-            break;
           }
         }
+      } catch(e) {
+        // Model store not accessible
       }
-    } catch(e) {
-      // Monaco API not available, continue
     }
-    // Fallback: Extract from view-lines
+    // Method 4: Fallback - Extract from view-lines (visible lines only)
     if (!result.content) {
       const viewLines = targetDoc.querySelector('.monaco-editor .view-lines');
       if (viewLines) {
@@ -316,25 +384,62 @@ export async function captureEditor(cdp) {
           let minLineNum = Infinity, maxLineNum = 0;
           const lineMap = new Map();
+          // Get line height from first line for accurate line number calculation
+          let lineHeight = 19;
+          if (lines[0]) {
+            const firstLineTop = parseFloat(lines[0].style.top) || 0;
+            const secondLine = lines[1];
+            if (secondLine) {
+              const secondLineTop = parseFloat(secondLine.style.top) || 0;
+              if (secondLineTop > firstLineTop) {
+                lineHeight = secondLineTop - firstLineTop;
+              }
+            }
+          }
           lines.forEach(line => {
             const top = parseFloat(line.style.top) || 0;
-            const lineNum = Math.round(top / 19) + 1;
+            const lineNum = Math.round(top / lineHeight) + 1;
             lineMap.set(lineNum, line.textContent || '');
             minLineNum = Math.min(minLineNum, lineNum);
             maxLineNum = Math.max(maxLineNum, lineNum);
           });
-          for (let i = minLineNum; i <= Math.min(maxLineNum, minLineNum + 500); i++) {
+          // Get total line count from scrollbar or line numbers if available
+          let totalLines = maxLineNum;
+          const lineNumbersContainer = targetDoc.querySelector('.monaco-editor .line-numbers');
+          if (lineNumbersContainer) {
+            const lastLineNum = lineNumbersContainer.querySelector('.line-numbers:last-child');
+            if (lastLineNum) {
+              const num = parseInt(lastLineNum.textContent, 10);
+              if (!isNaN(num) && num > totalLines) totalLines = num;
+            }
+          }
+          // Also try to get total from editor's scrollable height
+          const scrollableElement = targetDoc.querySelector('.monaco-editor .monaco-scrollable-element');
+          if (scrollableElement) {
+            const scrollHeight = scrollableElement.scrollHeight;
+            const estimatedLines = Math.ceil(scrollHeight / lineHeight);
+            if (estimatedLines > totalLines) totalLines = estimatedLines;
+          }
+          for (let i = minLineNum; i <= maxLineNum; i++) {
             codeContent += (lineMap.get(i) || '') + '\\n';
           }
           result.content = codeContent;
-          result.lineCount = maxLineNum;
+          result.lineCount = totalLines;
           result.startLine = minLineNum;
+          result.endLine = maxLineNum;
           result.hasContent = codeContent.trim().length > 0;
-          if (minLineNum > 1) {
-            result.isPartial = true;
-            result.note = 'Showing lines ' + minLineNum + '-' + maxLineNum + '. Scroll in Kiro to see other parts.';
+          // Always mark as partial when using view-lines fallback
+          result.isPartial = true;
+          if (minLineNum > 1 || maxLineNum < totalLines) {
+            result.note = 'Showing lines ' + minLineNum + '-' + maxLineNum + ' of ' + totalLines + '. Use Explorer to open full file.';
+          } else {
+            result.note = 'Visible lines only. Use Explorer to open full file.';
           }
         }
       }

package/src/utils/network.js CHANGED Viewed

@@ -1,11 +1,19 @@
 /**
- * Network utilities
+ * Network utilities for cross-platform local IP detection
+ *
+ * Supports: Windows, macOS, Linux
+ *
+ * Node.js os.networkInterfaces() family property:
+ * - Node < 18.0.0: returns string ('IPv4' or 'IPv6')
+ * - Node 18.0.0 - 18.3.x: returns number (4 or 6)
+ * - Node >= 18.4.0: returns string ('IPv4' or 'IPv6')
  */
 import { networkInterfaces } from 'os';
 /**
  * Check if interface is IPv4
  * Handles both string ('IPv4') and number (4) family values
+ * for compatibility across Node.js versions
  * @param {object} iface - Network interface object
  * @returns {boolean}
  */
@@ -13,22 +21,66 @@ function isIPv4(iface) {
   return iface.family === 'IPv4' || iface.family === 4;
 }
+/**
+ * Check if interface name is a virtual/container interface to skip
+ * @param {string} name - Interface name
+ * @returns {boolean}
+ */
+function isVirtualInterface(name) {
+  const lowerName = name.toLowerCase();
+  const virtualPatterns = [
+    'vethernet',    // Windows WSL/Hyper-V
+    'docker',       // Docker
+    'vmware',       // VMware
+    'virtualbox',   // VirtualBox
+    'vbox',         // VirtualBox alternate
+    'virbr',        // Linux libvirt bridge
+    'br-',          // Docker bridge
+    'veth',         // Virtual ethernet
+    'tailscale',    // Tailscale VPN
+    'tun',          // VPN tunnel
+    'tap',          // VPN tap
+    'utun',         // macOS VPN
+    'awdl',         // Apple Wireless Direct Link
+    'llw',          // Apple Low Latency WLAN
+    'bridge',       // Bridge interfaces
+    'ham',          // Hamachi VPN
+    'zt',           // ZeroTier
+  ];
+  return virtualPatterns.some(pattern => lowerName.includes(pattern));
+}
 /**
  * Get local IP address for LAN access
- * Returns the first non-internal IPv4 address found.
+ * Returns the first non-internal IPv4 address found, prioritizing
+ * physical network interfaces over virtual ones.
  *
- * NOTE: On systems with multiple network interfaces, this returns the first one found.
- * For more control, consider using environment variables or configuration.
+ * Platform-specific interface names:
+ * - Windows: 'Ethernet', 'Wi-Fi', 'Ethernet 2', 'Local Area Connection'
+ * - macOS: 'en0' (Wi-Fi), 'en1' (Ethernet), 'en2', etc.
+ * - Linux: 'eth0', 'enp0s3', 'ens33', 'wlan0', 'wlp2s0'
  *
  * @returns {string} - Local IP or 'localhost' if no suitable interface found
  */
 export function getLocalIP() {
   const interfaces = networkInterfaces();
-  // Prioritize common interface names (Linux, macOS, Windows)
-  const priorityInterfaces = ['Ethernet', 'Wi-Fi', 'eth0', 'en0', 'wlan0'];
+  // Priority 1: Common physical interface names across platforms
+  // Order matters - check most common first
+  const priorityInterfaces = [
+    // Windows
+    'Ethernet', 'Wi-Fi', 'Ethernet 2', 'Local Area Connection',
+    // macOS
+    'en0', 'en1', 'en2', 'en3', 'en4', 'en5',
+    // Linux (traditional)
+    'eth0', 'eth1', 'wlan0', 'wlan1',
+    // Linux (systemd predictable names)
+    'enp0s3', 'enp0s25', 'enp0s31f6', 'ens33', 'ens160', 'ens192',
+    'wlp2s0', 'wlp3s0', 'wlp0s20f3',
+  ];
-  // First, try priority interfaces
+  // First pass: try priority interfaces
   for (const name of priorityInterfaces) {
     const ifaces = interfaces[name];
     if (ifaces) {
@@ -40,15 +92,10 @@ export function getLocalIP() {
     }
   }
-  // Fallback: return first non-internal IPv4 (skip virtual/WSL interfaces)
+  // Second pass: any non-virtual interface
   for (const name of Object.keys(interfaces)) {
-    // Skip virtual interfaces (WSL, Docker, VPN, etc.)
-    if (name.toLowerCase().includes('vethernet') ||
-        name.toLowerCase().includes('docker') ||
-        name.toLowerCase().includes('vmware') ||
-        name.toLowerCase().includes('virtualbox')) {
-      continue;
-    }
+    if (isVirtualInterface(name)) continue;
     for (const iface of interfaces[name]) {
       if (isIPv4(iface) && !iface.internal) {
         return iface.address;
@@ -56,7 +103,7 @@ export function getLocalIP() {
     }
   }
-  // Last resort: any non-internal IPv4
+  // Last resort: any non-internal IPv4 (including virtual)
   for (const name of Object.keys(interfaces)) {
     for (const iface of interfaces[name]) {
       if (isIPv4(iface) && !iface.internal) {