fix(browse): resolve findPort() race condition in Node.js polyfill

[evb87-tech]

Summary

• Replace Bun.serve() port probing in findPort() with net.createServer() using proper async bind/close
• Fixes EADDRINUSE on Windows where the Node.js polyfill's async listen()/close() creates a race condition

Fixes #486

Problem

findPort() tests port availability by calling Bun.serve({ port }) then testServer.stop(). In real Bun, both are synchronous. In the Node.js polyfill (Windows), they wrap http.createServer() + server.listen() / server.close() — both async. Neither completes before findPort() returns:

1. findPort() → polyfill Bun.serve({ port: X })  → queues async listen()
2. testServer.stop()                               → queues async close()
3. findPort() returns X                            (nothing completed yet)
4. await browserManager.launch()                   → event loop runs
5. listen() NOW binds port X                       ← test server grabs the port
6. Real Bun.serve({ port: X })                     → EADDRINUSE (100% repro)

Root cause: the polyfill's stop() returns undefined (fire-and-forget), not a Promise — callers cannot await socket teardown.

Fix

New isPortAvailable() helper using net.createServer() with Promise-based bind/close:

function isPortAvailable(port: number, hostname: string = '127.0.0.1'): Promise<boolean> {
  return new Promise((resolve) => {
    const srv = net.createServer();
    srv.once('error', () => resolve(false));
    srv.listen(port, hostname, () => {
      srv.close(() => resolve(true));
    });
  });
}

This properly awaits both bind AND close before returning. Works on both Bun (where net is available) and Node.js.

Changes

• browse/src/server.ts: +18/-10 lines
  • Add import * as net from 'net'
  • Add isPortAvailable() helper
  • Replace both Bun.serve() port probes in findPort() with await isPortAvailable(port)
• browse/test/findport.test.ts: 6 new tests (all passing)

Test results

bun test browse/test/findport.test.ts

 6 pass
 0 fail
 7 expect() calls
Ran 6 tests across 1 file. [76.00ms]

Tests verify:

• isPortAvailable returns true for free ports
• isPortAvailable returns false for occupied ports
• Port is actually free after isPortAvailable returns (no leaked sockets)
• Polyfill stop() is fire-and-forget (documents root cause)
• net.createServer approach releases ports cleanly (proves fix)
• Rapid sequential port checks don't leak (stress test, 5 iterations)
• Existing bun-polyfill.test.ts passes (4/4, no regression)
• Full browse/test/ suite: 147/151 pass (4 pre-existing failures from missing playwright/diff packages)