@wong2kim/wmux 1.1.1 → 2.0.0

package/README.md

@@ -2,25 +2,40 @@
 
 **AI Agent Terminal for Windows**
 
-Run Claude Code, Codex, Gemini CLI side by side — with built-in browser, smart notifications, and MCP integration.
+Run Claude Code, Codex, Gemini CLI side by side — with built-in browser automation, smart notifications, and MCP integration.
 
 Inspired by [cmux](https://github.com/manaflow-ai/cmux) (macOS), wmux brings the same philosophy to Windows: **a primitive, not a solution.** Composable building blocks for multi-agent workflows.
 
 ![Windows](https://img.shields.io/badge/Windows-10%2F11-0078D6?logo=windows)
 ![Electron](https://img.shields.io/badge/Electron-41-47848F?logo=electron)
+![npm](https://img.shields.io/npm/v/@wong2kim/wmux?color=CB3837&logo=npm)
 ![License](https://img.shields.io/badge/License-MIT-green)
 
 ---
 
 ## Install
 
-**Download:** [wmux-1.1.1 Setup.exe](https://github.com/openwong2kim/wmux/releases/latest)
+**Download:** [wmux-2.0.0 Setup.exe](https://github.com/openwong2kim/wmux/releases/latest)
 
 Or build from source:
 ```powershell
 irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex
 ```
 
+**npm (CLI + MCP server only):**
+```bash
+npm install -g @wong2kim/wmux
+```
+
+---
+
+## What's New in v2.0.0
+
+- **Browser automation via CDP** — Click, fill, type, screenshot directly through Chrome DevTools Protocol. Works with React inputs, CJK text, and controlled components.
+- **Security hardening** — Token auth on all pipes, SSRF protection, input sanitization, randomized CDP ports, memory pressure watchdog.
+- **Workspace reset** — One-click reset in Settings to clean all workspaces and start fresh.
+- **Daemon process** — Background session management with suspend/resume, scrollback persistence, and auto-recovery.
+
 ---
 
 ## Why wmux?
@@ -28,7 +43,7 @@ irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex
 | Problem | wmux |
 |---------|------|
 | Windows has no cmux | Native Windows terminal multiplexer for AI agents |
-| Agents can't see the browser | Built-in browser with MCP — Claude clicks, fills, evaluates JS |
+| Agents can't control the browser | Built-in browser with CDP — Claude clicks, fills, types, screenshots |
 | "Is it done yet?" | Smart activity-based notifications + taskbar flash |
 | Can't compare agents | Multiview — Ctrl+click workspaces to view side by side |
 | Hard to describe UI elements to LLM | Inspector — click any element, LLM-friendly context copied |
@@ -45,27 +60,25 @@ irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex
 - **Vi copy mode** — `Ctrl+Shift+X`
 - **Search** — `Ctrl+F`
 - **Unlimited scrollback** — 999,999 lines default
+- **Scrollback persistence** — terminal content saved to disk, restored on restart
 
 ### Workspaces
 - Sidebar with drag-and-drop reordering
 - `Ctrl+1` ~ `Ctrl+9` quick switch
 - **Multiview** — `Ctrl+click` workspaces to split-view them simultaneously
-- `Ctrl+Shift+G` to exit multiview
-- Session persistence — everything restored on restart
+- **Session persistence** — workspace layout, tabs, cwd, and terminal scrollback all restored on restart
+- **One-click reset** — Settings > General > Reset to clean all workspaces
 
-### Browser
+### Browser + CDP Automation
 - Built-in browser panel — `Ctrl+Shift+L`
 - Navigation bar, DevTools, back/forward
-- **Element Inspector** — magnifying glass button to inspect elements
-  - Hover to highlight, click to copy LLM-friendly context:
-    ```
-    [Inspector] Google (https://www.google.com/)
-    selector: input.gLFyf
-    <input type="text" name="q" aria-label="Search">
-    text: ""
-    parent: div.RNNXgb > siblings: button"Google Search", button"I'm Feeling Lucky"
-    ```
-  - Paste directly into Claude — it understands the element immediately
+- **Element Inspector** — hover to highlight, click to copy LLM-friendly context
+- **Full CDP automation via MCP:**
+  - Click elements by ref or CSS selector
+  - Fill forms with real keyboard input (handles React, CJK)
+  - Take screenshots via CDP `Page.captureScreenshot`
+  - Evaluate JavaScript with user gesture context
+  - Navigate, go back, press keys
 
 ### Notifications
 - **Activity-based detection** — monitors output throughput, no fragile pattern matching
@@ -82,10 +95,16 @@ wmux automatically registers its MCP server when launched. Claude Code can:
 |------|-------------|
 | `browser_open` | Open a new browser panel |
 | `browser_navigate` | Go to URL |
-| `browser_snapshot` | Get full page HTML |
-| `browser_click` | Click element by CSS selector |
-| `browser_fill` | Fill input field |
-| `browser_eval` | Execute JavaScript |
+| `browser_screenshot` | Capture page as PNG (CDP) |
+| `browser_snapshot` | Get page structure with interactive element refs |
+| `browser_click` | Click element by ref number |
+| `browser_fill` | Fill form fields by ref |
+| `browser_type` | Type text into element (CDP keyboard input) |
+| `browser_press_key` | Press keyboard key (Enter, Tab, etc.) |
+| `browser_evaluate` | Execute JavaScript in page context |
+| `browser_hover` | Hover over element |
+| `browser_select` | Select dropdown options |
+| `browser_scroll_into_view` | Scroll element into viewport |
 | `terminal_read` | Read terminal screen |
 | `terminal_send` | Send text to terminal |
 | `terminal_send_key` | Send key (enter, ctrl+c, etc.) |
@@ -95,12 +114,26 @@ wmux automatically registers its MCP server when launched. Claude Code can:
 
 **Multi-agent:** All browser tools accept `surfaceId` — each Claude Code session controls its own browser independently.
 
+### Security
+- **Token authentication** on all IPC pipes (named pipe + session pipes)
+- **SSRF protection** — URL validation blocks private IPs, file://, javascript: schemes
+- **Input sanitization** — PTY command injection prevention
+- **CDP port randomization** — no fixed debug port
+- **Memory pressure watchdog** — auto-reaps dead sessions at 750MB, blocks new at 1GB
+- **Electron Fuses** — RunAsNode disabled, cookie encryption enabled
+
 ### Agent Status Detection
 Gate-based detection for AI coding agents:
 - Claude Code, Cursor, Aider, Codex CLI, Gemini CLI, OpenCode, GitHub Copilot CLI
-- Detects agent startup → activates monitoring
+- Detects agent startup, monitors activity
 - Critical action warnings (git push --force, rm -rf, DROP TABLE, etc.)
 
+### Daemon Process
+- Background session management (survives app restart)
+- Suspend/resume with scrollback buffer dump
+- Auto-recovery of sessions on daemon restart
+- Dead session TTL reaping (24h default)
+
 ### Themes
 Catppuccin, Tokyo Night, Dracula, Nord, Gruvbox, Solarized, One Dark, and more.
 
@@ -171,32 +204,48 @@ The `install.ps1` script auto-installs Python and VS Build Tools if missing.
 
 ```
 Electron Main Process
-├── PTYManager (node-pty)
+├── PTYManager (node-pty / ConPTY)
 ├── PTYBridge (data forwarding + ActivityMonitor)
 ├── AgentDetector (gate-based agent status)
-├── PipeServer (Named Pipe JSON-RPC)
+├── SessionManager (atomic save with .bak recovery)
+├── ScrollbackPersistence (dump/load terminal buffers)
+├── PipeServer (Named Pipe JSON-RPC + token auth)
 ├── McpRegistrar (auto-registers MCP in ~/.claude.json)
+├── WebviewCdpManager (CDP proxy to <webview> via debugger)
+├── DaemonClient (optional daemon mode connector)
 └── ToastManager (OS notifications + taskbar flash)
 
 Renderer Process (React 19 + Zustand)
 ├── PaneContainer (recursive split layout)
-├── Terminal (xterm.js + WebGL)
-├── BrowserPanel (webview + Inspector)
+├── Terminal (xterm.js + WebGL + scrollback restore)
+├── BrowserPanel (webview + Inspector + CDP)
 ├── NotificationPanel
+├── SettingsPanel (workspace reset)
 └── Multiview grid
 
+Daemon Process (optional, standalone)
+├── DaemonSessionManager (ConPTY lifecycle)
+├── RingBuffer (circular scrollback buffer)
+├── StateWriter (session suspend/resume)
+├── ProcessMonitor (external process watchdog)
+├── Watchdog (memory pressure escalation)
+└── DaemonPipeServer (Named Pipe RPC + token auth)
+
 MCP Server (stdio)
-└── Bridges Claude Code ↔ wmux via Named Pipe RPC
+├── PlaywrightEngine (CDP connection, fast-fail)
+├── CDP RPC fallback (browser.screenshot, browser.evaluate, etc.)
+└── Bridges Claude Code <-> wmux via Named Pipe RPC
 ```
 
 ---
 
 ## Acknowledgments
 
-- [cmux](https://github.com/manaflow-ai/cmux) — The macOS AI agent terminal that inspired wmux. Same philosophy: primitives over prescriptive workflows.
+- [cmux](https://github.com/manaflow-ai/cmux) — The macOS AI agent terminal that inspired wmux
 - [xterm.js](https://xtermjs.org/) — Terminal rendering
 - [node-pty](https://github.com/microsoft/node-pty) — Pseudo-terminal
 - [Electron](https://www.electronjs.org/) — Desktop framework
+- [Playwright](https://playwright.dev/) — Browser automation engine
 
 ---
 

package/dist/cli/cli/commands/browser.js

@@ -4,24 +4,25 @@ exports.handleBrowser = handleBrowser;
 const client_1 = require("../client");
 const utils_1 = require("../utils");
 const BROWSER_HELP = `
-wmux browser — Scriptable Browser API
+wmux browser — Browser Commands
 
 USAGE
   wmux browser <subcommand> [args]
 
 SUBCOMMANDS
-  snapshot                        Return the full page HTML (document.documentElement.outerHTML)
-  click <selector>                Click the first element matching the CSS selector
-  fill <selector> <text>          Set the value of an input matching the CSS selector
-  eval <code>                     Execute arbitrary JavaScript in the page context
   navigate <url>                  Navigate the active browser surface to a URL
+  close                           Close the browser panel
+  session start [--profile <name>]  Start a browser session
+  session stop                      Stop the active browser session
+  session status                    Show active session status
+  session list                      List available profiles
 
 EXAMPLES
-  wmux browser snapshot
-  wmux browser click "#submit-btn"
-  wmux browser fill "input[name=email]" "user@example.com"
-  wmux browser eval "document.title"
   wmux browser navigate "https://example.com"
+  wmux browser close
+  wmux browser session start --profile login
+  wmux browser session status
+  wmux browser session list
 `.trimStart();
 async function handleBrowser(args, jsonMode) {
     const sub = args[0];
@@ -32,30 +33,14 @@ async function handleBrowser(args, jsonMode) {
     }
     let response;
     switch (sub) {
-        // ── browser snapshot ─────────────────────────────────────────────────────
-        case 'snapshot': {
-            response = await (0, client_1.sendRequest)('browser.snapshot', {});
-            if (jsonMode) {
-                (0, utils_1.printResult)(response);
-            }
-            else {
-                if (!response.ok) {
-                    (0, utils_1.printError)(response);
-                    return;
-                }
-                const r = response.result;
-                process.stdout.write(r?.html ?? '');
-            }
-            break;
-        }
-        // ── browser click <selector> ─────────────────────────────────────────────
-        case 'click': {
-            const selector = rest[0];
-            if (!selector) {
-                console.error('Error: browser click requires <selector>');
+        // ── browser navigate <url> ───────────────────────────────────────────────
+        case 'navigate': {
+            const url = rest[0];
+            if (!url) {
+                console.error('Error: browser navigate requires <url>');
                 process.exit(1);
             }
-            response = await (0, client_1.sendRequest)('browser.click', { selector });
+            response = await (0, client_1.sendRequest)('browser.navigate', { url });
             if (jsonMode) {
                 (0, utils_1.printResult)(response);
             }
@@ -64,19 +49,13 @@ async function handleBrowser(args, jsonMode) {
                     (0, utils_1.printError)(response);
                     return;
                 }
-                console.log(`Clicked: ${selector}`);
+                console.log(`Navigated to: ${url}`);
             }
             break;
         }
-        // ── browser fill <selector> <text> ───────────────────────────────────────
-        case 'fill': {
-            const selector = rest[0];
-            const text = rest.slice(1).join(' ');
-            if (!selector) {
-                console.error('Error: browser fill requires <selector> <text>');
-                process.exit(1);
-            }
-            response = await (0, client_1.sendRequest)('browser.fill', { selector, text });
+        // ── browser close ────────────────────────────────────────────────────────
+        case 'close': {
+            response = await (0, client_1.sendRequest)('browser.close', {});
             if (jsonMode) {
                 (0, utils_1.printResult)(response);
             }
@@ -85,48 +64,93 @@ async function handleBrowser(args, jsonMode) {
                     (0, utils_1.printError)(response);
                     return;
                 }
-                console.log(`Filled "${selector}" with "${text}"`);
+                console.log('Browser panel closed.');
             }
             break;
         }
-        // ── browser eval <code> ──────────────────────────────────────────────────
-        case 'eval': {
-            const code = rest.join(' ');
-            if (!code) {
-                console.error('Error: browser eval requires <code>');
-                process.exit(1);
-            }
-            response = await (0, client_1.sendRequest)('browser.eval', { code });
-            if (jsonMode) {
-                (0, utils_1.printResult)(response);
+        // ── browser session <action> ─────────────────────────────────────────────
+        case 'session': {
+            const action = rest[0];
+            if (!action || action === '--help' || action === '-h') {
+                console.log('Usage: wmux browser session <start|stop|status|list>');
+                process.exit(0);
             }
-            else {
-                if (!response.ok) {
-                    (0, utils_1.printError)(response);
-                    return;
+            switch (action) {
+                case 'start': {
+                    const profileIdx = rest.indexOf('--profile');
+                    const profile = profileIdx !== -1 ? rest[profileIdx + 1] : undefined;
+                    const params = {};
+                    if (profile)
+                        params['profile'] = profile;
+                    response = await (0, client_1.sendRequest)('browser.session.start', params);
+                    if (jsonMode) {
+                        (0, utils_1.printResult)(response);
+                    }
+                    else {
+                        if (!response.ok) {
+                            (0, utils_1.printError)(response);
+                            return;
+                        }
+                        const r = response.result;
+                        console.log(`Session started with profile: ${r['profile'] ?? 'default'}`);
+                    }
+                    break;
                 }
-                const r = response.result;
-                console.log(JSON.stringify(r?.result, null, 2));
-            }
-            break;
-        }
-        // ── browser navigate <url> ───────────────────────────────────────────────
-        case 'navigate': {
-            const url = rest[0];
-            if (!url) {
-                console.error('Error: browser navigate requires <url>');
-                process.exit(1);
-            }
-            response = await (0, client_1.sendRequest)('browser.navigate', { url });
-            if (jsonMode) {
-                (0, utils_1.printResult)(response);
-            }
-            else {
-                if (!response.ok) {
-                    (0, utils_1.printError)(response);
-                    return;
+                case 'stop': {
+                    response = await (0, client_1.sendRequest)('browser.session.stop', {});
+                    if (jsonMode) {
+                        (0, utils_1.printResult)(response);
+                    }
+                    else {
+                        if (!response.ok) {
+                            (0, utils_1.printError)(response);
+                            return;
+                        }
+                        console.log('Session stopped.');
+                    }
+                    break;
                 }
-                console.log(`Navigated to: ${url}`);
+                case 'status': {
+                    response = await (0, client_1.sendRequest)('browser.session.status', {});
+                    if (jsonMode) {
+                        (0, utils_1.printResult)(response);
+                    }
+                    else {
+                        if (!response.ok) {
+                            (0, utils_1.printError)(response);
+                            return;
+                        }
+                        const r = response.result;
+                        console.log(`Active profile: ${r['profile'] ?? 'none'}`);
+                        console.log(`CDP port: ${r['port'] ?? 'none'}`);
+                    }
+                    break;
+                }
+                case 'list': {
+                    response = await (0, client_1.sendRequest)('browser.session.list', {});
+                    if (jsonMode) {
+                        (0, utils_1.printResult)(response);
+                    }
+                    else {
+                        if (!response.ok) {
+                            (0, utils_1.printError)(response);
+                            return;
+                        }
+                        const profiles = response.result['profiles'];
+                        if (!profiles || profiles.length === 0) {
+                            console.log('No profiles found.');
+                        }
+                        else {
+                            for (const p of profiles) {
+                                console.log(`  ${p['name']}  (partition: ${p['partition']}, persistent: ${p['persistent']})`);
+                            }
+                        }
+                    }
+                    break;
+                }
+                default:
+                    console.error(`Unknown session action: "${action}". Use start, stop, status, or list.`);
+                    process.exit(1);
             }
             break;
         }

package/dist/cli/cli/index.js

@@ -51,11 +51,12 @@ SYSTEM COMMANDS
   capabilities                      List all supported RPC methods
 
 BROWSER COMMANDS
-  browser snapshot                  Return the full page HTML of the active browser surface
-  browser click <selector>          Click an element by CSS selector
-  browser fill <selector> <text>    Fill an input field by CSS selector
-  browser eval <code>               Execute JavaScript in the browser context
   browser navigate <url>            Navigate the browser surface to a URL
+  browser close                     Close the browser panel
+  browser session start [--profile <name>]  Start a browser session
+  browser session stop              Stop the active browser session
+  browser session status            Show active session status
+  browser session list              List available profiles
 
 GLOBAL FLAGS
   --json      Output raw JSON (useful for scripting)
@@ -67,9 +68,8 @@ EXAMPLES
   wmux send "echo hello"
   wmux notify --title "Done" --body "Build finished"
   wmux identify --json
-  wmux browser snapshot
   wmux browser navigate "https://example.com"
-  wmux browser click "#login-btn"
+  wmux browser close
 `.trimStart();
 const WORKSPACE_CMDS = new Set([
     'list-workspaces',

package/dist/cli/shared/constants.js

@@ -45,6 +45,9 @@ exports.IPC = {
     FS_WATCH: 'fs:watch',
     FS_UNWATCH: 'fs:unwatch',
     FS_CHANGED: 'fs:changed',
+    // Scrollback persistence
+    SCROLLBACK_DUMP: 'scrollback:dump',
+    SCROLLBACK_LOAD: 'scrollback:load',
 };
 // Named Pipe / Unix socket path for wmux API
 // Fixed name so MCP clients (e.g. Claude Code) can reconnect across wmux restarts

package/dist/cli/shared/rpc.js

@@ -25,9 +25,26 @@ exports.ALL_RPC_METHODS = [
     'system.identify',
     'system.capabilities',
     'browser.open',
-    'browser.snapshot',
-    'browser.click',
-    'browser.fill',
-    'browser.eval',
     'browser.navigate',
+    'browser.close',
+    'browser.session.start',
+    'browser.session.stop',
+    'browser.session.status',
+    'browser.session.list',
+    'browser.type.humanlike',
+    'browser.cdp.target',
+    'browser.cdp.info',
+    'browser.cdp.send',
+    'browser.screenshot',
+    'browser.evaluate',
+    'browser.type.cdp',
+    'browser.click.cdp',
+    'browser.press.cdp',
+    'daemon.createSession',
+    'daemon.destroySession',
+    'daemon.attachSession',
+    'daemon.detachSession',
+    'daemon.resizeSession',
+    'daemon.listSessions',
+    'daemon.ping',
 ];

package/dist/cli/shared/types.js

@@ -7,19 +7,22 @@ exports.validateMessage = validateMessage;
 exports.createSurface = createSurface;
 exports.createLeafPane = createLeafPane;
 exports.createWorkspace = createWorkspace;
+exports.validateNavigationUrl = validateNavigationUrl;
 // === Utility: generate unique IDs ===
 function generateId(prefix) {
     return `${prefix}-${crypto.randomUUID()}`;
 }
 // === Security: sanitize text before PTY write ===
 /**
- * Strips control characters (\r, \n, \x00-\x1f except \t) from text
- * that will be written to a PTY, preventing embedded command injection.
+ * Strips dangerous control characters from text before writing to a PTY.
+ * Removes: NULL byte (\x00) and C1 control characters (\x80-\x9f).
+ * Preserves: CR (\r), LF (\n), Tab (\t), ESC sequences (\x1b[...),
+ * and other standard terminal control characters needed for normal operation.
  */
 function sanitizePtyText(text) {
-    // Remove all control chars except tab (\x09)
+    // Remove NULL byte and C1 control characters (U+0080–U+009F)
     // eslint-disable-next-line no-control-regex
-    return text.replace(/[\x00-\x08\x0a-\x1f\x7f\u0080-\u009f]/g, '');
+    return text.replace(/[\x00\u0080-\u009f]/g, '');
 }
 /**
  * Validates and clamps a user-supplied name string.
@@ -77,3 +80,104 @@ function createWorkspace(name) {
         activePaneId: rootPane.id,
     };
 }
+// === Security: URL validation for SSRF prevention ===
+/**
+ * Validates a URL for safe navigation. Blocks dangerous schemes and private
+ * network addresses to prevent SSRF attacks from AI agent-driven browsing.
+ *
+ * Allows localhost/127.0.0.1/[::1] for local development servers.
+ *
+ * NOTE (v1 limitation): This is string-based validation only. DNS-resolved IPs
+ * are not checked, so DNS rebinding attacks are not mitigated. A future version
+ * should resolve hostnames and re-validate the resolved IP.
+ */
+function validateNavigationUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { valid: false, reason: 'Invalid URL' };
+    }
+    // Only allow http and https schemes
+    const scheme = parsed.protocol.toLowerCase();
+    if (scheme !== 'http:' && scheme !== 'https:') {
+        return { valid: false, reason: `Blocked URL scheme: ${scheme}` };
+    }
+    // Extract hostname (strip brackets from IPv6)
+    const hostname = parsed.hostname.toLowerCase();
+    // Allow localhost and IPv4/IPv6 loopback
+    if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+        return { valid: true };
+    }
+    // Block IPv6 private/link-local ranges
+    if (hostname.startsWith('[') || hostname.includes(':')) {
+        // Hostname is an IPv6 address (URL parser strips brackets in .hostname)
+        const addr = hostname;
+        // Block fc00::/7 (unique local) — starts with fc or fd
+        if (addr.startsWith('fc') || addr.startsWith('fd')) {
+            return { valid: false, reason: 'Blocked private IPv6 address (fc00::/7)' };
+        }
+        // Block fe80::/10 (link-local) — starts with fe8, fe9, fea, feb
+        if (/^fe[89ab]/.test(addr)) {
+            return { valid: false, reason: 'Blocked link-local IPv6 address (fe80::/10)' };
+        }
+        // ::1 already allowed above; block any other loopback representation
+        // Normalize: collapse :: and check
+        if (addr === '0:0:0:0:0:0:0:1' || addr === '0000:0000:0000:0000:0000:0000:0000:0001') {
+            return { valid: true };
+        }
+        // Block null IPv6 address (:: or 0:0:0:0:0:0:0:0) — equivalent to 0.0.0.0
+        if (addr === '::' || addr === '0:0:0:0:0:0:0:0' || addr === '0000:0000:0000:0000:0000:0000:0000:0000') {
+            return { valid: false, reason: 'Blocked null IPv6 address (equivalent to 0.0.0.0)' };
+        }
+        // Block IPv4-mapped IPv6 (::ffff:x.x.x.x) and IPv4-compatible IPv6 (::x.x.x.x)
+        // These resolve to their embedded IPv4 address, bypassing IPv4 private IP checks.
+        const v4MappedMatch = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(addr);
+        const v4CompatMatch = !v4MappedMatch ? /^::(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(addr) : null;
+        const embeddedV4 = v4MappedMatch?.[1] ?? v4CompatMatch?.[1];
+        if (embeddedV4) {
+            // Recursively validate the embedded IPv4 through the same checks
+            const embeddedResult = validateNavigationUrl(`http://${embeddedV4}/`);
+            if (!embeddedResult.valid) {
+                return { valid: false, reason: `Blocked IPv4-mapped/compatible IPv6: embedded ${embeddedV4} — ${embeddedResult.reason}` };
+            }
+        }
+        return { valid: true };
+    }
+    // Check for IPv4 addresses
+    const ipv4Match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
+    if (ipv4Match) {
+        const octets = [
+            parseInt(ipv4Match[1], 10),
+            parseInt(ipv4Match[2], 10),
+            parseInt(ipv4Match[3], 10),
+            parseInt(ipv4Match[4], 10),
+        ];
+        // 127.0.0.1 already allowed above; block other 127.x.x.x
+        if (octets[0] === 127) {
+            return { valid: false, reason: 'Blocked loopback address' };
+        }
+        // Block 10.0.0.0/8
+        if (octets[0] === 10) {
+            return { valid: false, reason: 'Blocked private IP address (10.0.0.0/8)' };
+        }
+        // Block 172.16.0.0/12 (172.16.x.x – 172.31.x.x)
+        if (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) {
+            return { valid: false, reason: 'Blocked private IP address (172.16.0.0/12)' };
+        }
+        // Block 192.168.0.0/16
+        if (octets[0] === 192 && octets[1] === 168) {
+            return { valid: false, reason: 'Blocked private IP address (192.168.0.0/16)' };
+        }
+        // Block 169.254.0.0/16 (link-local, includes cloud metadata 169.254.169.254)
+        if (octets[0] === 169 && octets[1] === 254) {
+            return { valid: false, reason: 'Blocked link-local/cloud metadata address (169.254.0.0/16)' };
+        }
+        // Block 0.0.0.0
+        if (octets.every((o) => o === 0)) {
+            return { valid: false, reason: 'Blocked null address (0.0.0.0)' };
+        }
+    }
+    return { valid: true };
+}