@hydranium/core 1.0.0-next.51 → 1.0.0-next.52

package/lib/testing/playwright/flaky-network-proxy.d.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/**
+ * A TCP proxy that can half-close a connection, so an e2e suite can reproduce a
+ * flaky network against a real browser session.
+ *
+ * Toggling the browser offline is not enough. On localhost the server sees the
+ * close immediately and reaps the socket before the browser reconnects, so the
+ * window where both sides disagree about the session — the one where reconnect
+ * defects live — never opens. Reaching it needs the browser's socket to die
+ * while the server still believes it is alive, and nothing inside the app or in
+ * Playwright's offline emulation can produce that asymmetry: both close cleanly
+ * at both ends.
+ *
+ * The proxy holds both halves of every connection and lets a test kill them
+ * independently:
+ *
+ *   `break`    destroy the BROWSER-side sockets, keep the server-side ones open.
+ *              The browser reconnects through a fresh pair while the server
+ *              still holds the old one.
+ *   `release`  destroy the orphaned server-side sockets `break` left. The
+ *              server's disconnect handler fires at once, rather than whenever
+ *              its next heartbeat write would have failed.
+ */
+/** Where the proxy listens, and the application it fronts. */
+export interface FlakyNetworkProxyOptions {
+    /** Port the browser connects to. */
+    readonly listenPort: number;
+    /** Port of the application being proxied. */
+    readonly targetPort: number;
+    /** Host of the application being proxied. Defaults to loopback. */
+    readonly targetHost?: string;
+    /** Port the HTTP control channel listens on. Defaults to `listenPort + 1000`. */
+    readonly controlPort?: number;
+}
+/** The commands the control channel accepts, and the proxy's own vocabulary. */
+export type FlakyNetworkCommand = 'break' | 'release' | 'status';
+/** Drives a running proxy. Implemented both in-process and over HTTP. */
+export interface FlakyNetworkControl {
+    /** Kill the browser side of every live connection; leave the server side up. */
+    break(): Promise<string>;
+    /** Kill the server side of every connection `break` orphaned. */
+    release(): Promise<string>;
+    /** How many connections are live and how many are orphaned. */
+    status(): Promise<string>;
+}
+export interface FlakyNetworkProxy extends FlakyNetworkControl {
+    /** Base URL a browser should be pointed at, i.e. Playwright's `baseURL`. */
+    readonly url: string;
+    /** Control channel, for workers that cannot reach this object directly. */
+    readonly controlUrl: string;
+    close(): Promise<void>;
+}
+/**
+ * Starts the proxy in the calling process.
+ *
+ * Call it from a Playwright config, which runs in the main process before any
+ * worker forks. Workers are separate processes and cannot reach the returned
+ * object, which is what {@link controlUrl} and {@link flakyNetworkControlClient}
+ * are for.
+ */
+export declare function startFlakyNetworkProxy(options: FlakyNetworkProxyOptions): Promise<FlakyNetworkProxy>;
+/**
+ * Drives a proxy running in another process, over its control channel.
+ *
+ * This is what a spec uses: Playwright workers are separate processes from the
+ * config that started the proxy.
+ */
+export declare function flakyNetworkControlClient(controlUrl: string): FlakyNetworkControl;
+//# sourceMappingURL=flaky-network-proxy.d.ts.map

package/lib/testing/playwright/flaky-network-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flaky-network-proxy.d.ts","sourceRoot":"","sources":["../../../src/testing/playwright/flaky-network-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACtC,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjE,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IACjC,gFAAgF;IAChF,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,iEAAiE;IACjE,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,+DAA+D;IAC/D,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC3D,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AASD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyH1G;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAajF"}

package/lib/testing/playwright/flaky-network-proxy.js

@@ -0,0 +1,164 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { createServer as createHttpServer } from 'node:http';
+import { connect, createServer as createTcpServer } from 'node:net';
+/**
+ * Starts the proxy in the calling process.
+ *
+ * Call it from a Playwright config, which runs in the main process before any
+ * worker forks. Workers are separate processes and cannot reach the returned
+ * object, which is what {@link controlUrl} and {@link flakyNetworkControlClient}
+ * are for.
+ */
+export async function startFlakyNetworkProxy(options) {
+    const targetHost = options.targetHost ?? '127.0.0.1';
+    const controlPort = options.controlPort ?? options.listenPort + 1000;
+    const pairs = new Set();
+    let sequence = 0;
+    let transcript = [];
+    const log = (message) => {
+        transcript.push(message);
+        console.log(`[flaky-network] ${message}`);
+    };
+    const proxyServer = createTcpServer(browserSocket => {
+        const id = ++sequence;
+        const targetSocket = connect(options.targetPort, targetHost);
+        const pair = { id, browserSocket, targetSocket, orphaned: false };
+        pairs.add(pair);
+        // Forwarded by hand rather than with `pipe()`, so killing one side does not
+        // tear the other down — which is the entire point of the proxy.
+        browserSocket.on('data', chunk => {
+            if (!targetSocket.destroyed) {
+                targetSocket.write(chunk);
+            }
+        });
+        targetSocket.on('data', chunk => {
+            if (!pair.orphaned && !browserSocket.destroyed) {
+                browserSocket.write(chunk);
+            }
+        });
+        const teardown = (origin) => {
+            if (pair.orphaned && origin === 'browser') {
+                // Expected: `break` killed this side deliberately. The server side
+                // stays up until `release`.
+                return;
+            }
+            pairs.delete(pair);
+            browserSocket.destroy();
+            targetSocket.destroy();
+        };
+        browserSocket.on('close', () => teardown('browser'));
+        targetSocket.on('close', () => teardown('target'));
+        // A half-killed pair reliably raises ECONNRESET on the surviving side; an
+        // unhandled 'error' would take the whole runner down with it.
+        browserSocket.on('error', () => undefined);
+        targetSocket.on('error', () => undefined);
+    });
+    const commands = {
+        break: () => {
+            const live = [...pairs].filter(pair => !pair.orphaned);
+            if (live.length === 0) {
+                log('nothing to break');
+                return;
+            }
+            for (const pair of live) {
+                pair.orphaned = true;
+                pair.browserSocket.destroy();
+            }
+            log(`${live.length} connection(s) broken; the browser should reconnect shortly`);
+        },
+        release: () => {
+            const orphans = [...pairs].filter(pair => pair.orphaned);
+            if (orphans.length === 0) {
+                log('no orphaned connections; run `break` first');
+                return;
+            }
+            for (const pair of orphans) {
+                pairs.delete(pair);
+                pair.targetSocket.destroy();
+            }
+            log(`${orphans.length} orphaned connection(s) destroyed; their late disconnect fires now`);
+        },
+        status: () => {
+            const live = [...pairs].filter(pair => !pair.orphaned).length;
+            const orphaned = pairs.size - live;
+            log(`${live} live, ${orphaned} orphaned`);
+        }
+    };
+    const run = (name) => {
+        transcript = [];
+        const command = commands[name];
+        if (command) {
+            command();
+        }
+        else {
+            log(`unknown command '${name}'; use: ${Object.keys(commands).join(' | ')}`);
+        }
+        return transcript.join('\n');
+    };
+    const controlServer = createHttpServer((request, response) => {
+        const output = run((request.url ?? '').replace(/^\//, '').split('?')[0]);
+        response.writeHead(200, { 'content-type': 'text/plain' });
+        response.end(`${output}\n`);
+    });
+    await Promise.all([listen(proxyServer, options.listenPort), listen(controlServer, controlPort)]);
+    // Neither server keeps the process alive, so a runner that starts one from a
+    // config does not need a teardown hook to exit — and a caller that wants a
+    // deterministic shutdown still has `close()`.
+    proxyServer.unref();
+    controlServer.unref();
+    return {
+        url: `http://localhost:${options.listenPort}`,
+        controlUrl: `http://localhost:${controlPort}`,
+        break: async () => run('break'),
+        release: async () => run('release'),
+        status: async () => run('status'),
+        close: async () => {
+            for (const pair of pairs) {
+                pair.browserSocket.destroy();
+                pair.targetSocket.destroy();
+            }
+            pairs.clear();
+            await Promise.all([close(proxyServer), close(controlServer)]);
+        }
+    };
+}
+/**
+ * Drives a proxy running in another process, over its control channel.
+ *
+ * This is what a spec uses: Playwright workers are separate processes from the
+ * config that started the proxy.
+ */
+export function flakyNetworkControlClient(controlUrl) {
+    const send = async (command) => {
+        const response = await fetch(`${controlUrl}/${command}`);
+        if (!response.ok) {
+            throw new Error(`flaky-network proxy rejected '${command}': ${response.status}`);
+        }
+        return (await response.text()).trim();
+    };
+    return {
+        break: () => send('break'),
+        release: () => send('release'),
+        status: () => send('status')
+    };
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+}
+function close(server) {
+    return new Promise(resolve => server.close(() => resolve()));
+}
+//# sourceMappingURL=flaky-network-proxy.js.map

package/lib/testing/playwright/flaky-network-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flaky-network-proxy.js","sourceRoot":"","sources":["../../../src/testing/playwright/flaky-network-proxy.ts"],"names":[],"mappings":"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"}

package/lib/testing/playwright/index.d.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 export * from './e2e-profiling.js';
+export * from './flaky-network-proxy.js';
 export * from './browser-capture-bridge.js';
 export * from './server-log-capture.js';
 export * from './server-log-fixture.js';

package/lib/testing/playwright/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/playwright/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/playwright/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC"}

package/lib/testing/playwright/index.js

@@ -10,6 +10,7 @@
 // `@hydranium/core/testing` barrel) so importing the framework's unit-test
 // helpers never pulls in `@playwright/test` — which is an OPTIONAL peer here.
 export * from './e2e-profiling.js';
+export * from './flaky-network-proxy.js';
 export * from './browser-capture-bridge.js';
 export * from './server-log-capture.js';
 export * from './server-log-fixture.js';

package/lib/testing/playwright/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/playwright/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/playwright/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/core",
-  "version": "1.0.0-next.51",
+  "version": "1.0.0-next.52",
   "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
   "keywords": [
     "hydranium",
@@ -104,8 +104,8 @@
     "diff": "^5.2.0"
   },
   "devDependencies": {
-    "@hydranium/langium": "1.0.0-next.51",
-    "@hydranium/protocol": "1.0.0-next.51",
+    "@hydranium/langium": "1.0.0-next.52",
+    "@hydranium/protocol": "1.0.0-next.52",
     "@playwright/test": "^1.40.0",
     "@types/diff": "^5.2.0",
     "rimraf": "^5.0.0",
@@ -117,8 +117,8 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "@hydranium/langium": "1.0.0-next.51",
-    "@hydranium/protocol": "1.0.0-next.51",
+    "@hydranium/langium": "1.0.0-next.52",
+    "@hydranium/protocol": "1.0.0-next.52",
     "@playwright/test": "^1.40.0",
     "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver": "~10.0.1",

package/src/testing/playwright/flaky-network-proxy.ts

@@ -0,0 +1,240 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { connect, createServer as createTcpServer, type Server as TcpServer, type Socket } from 'node:net';
+
+/**
+ * A TCP proxy that can half-close a connection, so an e2e suite can reproduce a
+ * flaky network against a real browser session.
+ *
+ * Toggling the browser offline is not enough. On localhost the server sees the
+ * close immediately and reaps the socket before the browser reconnects, so the
+ * window where both sides disagree about the session — the one where reconnect
+ * defects live — never opens. Reaching it needs the browser's socket to die
+ * while the server still believes it is alive, and nothing inside the app or in
+ * Playwright's offline emulation can produce that asymmetry: both close cleanly
+ * at both ends.
+ *
+ * The proxy holds both halves of every connection and lets a test kill them
+ * independently:
+ *
+ *   `break`    destroy the BROWSER-side sockets, keep the server-side ones open.
+ *              The browser reconnects through a fresh pair while the server
+ *              still holds the old one.
+ *   `release`  destroy the orphaned server-side sockets `break` left. The
+ *              server's disconnect handler fires at once, rather than whenever
+ *              its next heartbeat write would have failed.
+ */
+
+/** Where the proxy listens, and the application it fronts. */
+export interface FlakyNetworkProxyOptions {
+   /** Port the browser connects to. */
+   readonly listenPort: number;
+   /** Port of the application being proxied. */
+   readonly targetPort: number;
+   /** Host of the application being proxied. Defaults to loopback. */
+   readonly targetHost?: string;
+   /** Port the HTTP control channel listens on. Defaults to `listenPort + 1000`. */
+   readonly controlPort?: number;
+}
+
+/** The commands the control channel accepts, and the proxy's own vocabulary. */
+export type FlakyNetworkCommand = 'break' | 'release' | 'status';
+
+/** Drives a running proxy. Implemented both in-process and over HTTP. */
+export interface FlakyNetworkControl {
+   /** Kill the browser side of every live connection; leave the server side up. */
+   break(): Promise<string>;
+   /** Kill the server side of every connection `break` orphaned. */
+   release(): Promise<string>;
+   /** How many connections are live and how many are orphaned. */
+   status(): Promise<string>;
+}
+
+export interface FlakyNetworkProxy extends FlakyNetworkControl {
+   /** Base URL a browser should be pointed at, i.e. Playwright's `baseURL`. */
+   readonly url: string;
+   /** Control channel, for workers that cannot reach this object directly. */
+   readonly controlUrl: string;
+   close(): Promise<void>;
+}
+
+interface ConnectionPair {
+   readonly id: number;
+   readonly browserSocket: Socket;
+   readonly targetSocket: Socket;
+   orphaned: boolean;
+}
+
+/**
+ * Starts the proxy in the calling process.
+ *
+ * Call it from a Playwright config, which runs in the main process before any
+ * worker forks. Workers are separate processes and cannot reach the returned
+ * object, which is what {@link controlUrl} and {@link flakyNetworkControlClient}
+ * are for.
+ */
+export async function startFlakyNetworkProxy(options: FlakyNetworkProxyOptions): Promise<FlakyNetworkProxy> {
+   const targetHost = options.targetHost ?? '127.0.0.1';
+   const controlPort = options.controlPort ?? options.listenPort + 1000;
+   const pairs = new Set<ConnectionPair>();
+   let sequence = 0;
+   let transcript: string[] = [];
+
+   const log = (message: string): void => {
+      transcript.push(message);
+      console.log(`[flaky-network] ${message}`);
+   };
+
+   const proxyServer: TcpServer = createTcpServer(browserSocket => {
+      const id = ++sequence;
+      const targetSocket = connect(options.targetPort, targetHost);
+      const pair: ConnectionPair = { id, browserSocket, targetSocket, orphaned: false };
+      pairs.add(pair);
+
+      // Forwarded by hand rather than with `pipe()`, so killing one side does not
+      // tear the other down — which is the entire point of the proxy.
+      browserSocket.on('data', chunk => {
+         if (!targetSocket.destroyed) {
+            targetSocket.write(chunk);
+         }
+      });
+      targetSocket.on('data', chunk => {
+         if (!pair.orphaned && !browserSocket.destroyed) {
+            browserSocket.write(chunk);
+         }
+      });
+
+      const teardown = (origin: 'browser' | 'target'): void => {
+         if (pair.orphaned && origin === 'browser') {
+            // Expected: `break` killed this side deliberately. The server side
+            // stays up until `release`.
+            return;
+         }
+         pairs.delete(pair);
+         browserSocket.destroy();
+         targetSocket.destroy();
+      };
+
+      browserSocket.on('close', () => teardown('browser'));
+      targetSocket.on('close', () => teardown('target'));
+      // A half-killed pair reliably raises ECONNRESET on the surviving side; an
+      // unhandled 'error' would take the whole runner down with it.
+      browserSocket.on('error', () => undefined);
+      targetSocket.on('error', () => undefined);
+   });
+
+   const commands: Record<FlakyNetworkCommand, () => void> = {
+      break: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned);
+         if (live.length === 0) {
+            log('nothing to break');
+            return;
+         }
+         for (const pair of live) {
+            pair.orphaned = true;
+            pair.browserSocket.destroy();
+         }
+         log(`${live.length} connection(s) broken; the browser should reconnect shortly`);
+      },
+      release: () => {
+         const orphans = [...pairs].filter(pair => pair.orphaned);
+         if (orphans.length === 0) {
+            log('no orphaned connections; run `break` first');
+            return;
+         }
+         for (const pair of orphans) {
+            pairs.delete(pair);
+            pair.targetSocket.destroy();
+         }
+         log(`${orphans.length} orphaned connection(s) destroyed; their late disconnect fires now`);
+      },
+      status: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned).length;
+         const orphaned = pairs.size - live;
+         log(`${live} live, ${orphaned} orphaned`);
+      }
+   };
+
+   const run = (name: string): string => {
+      transcript = [];
+      const command = commands[name as FlakyNetworkCommand];
+      if (command) {
+         command();
+      } else {
+         log(`unknown command '${name}'; use: ${Object.keys(commands).join(' | ')}`);
+      }
+      return transcript.join('\n');
+   };
+
+   const controlServer: HttpServer = createHttpServer((request, response) => {
+      const output = run((request.url ?? '').replace(/^\//, '').split('?')[0]);
+      response.writeHead(200, { 'content-type': 'text/plain' });
+      response.end(`${output}\n`);
+   });
+
+   await Promise.all([listen(proxyServer, options.listenPort), listen(controlServer, controlPort)]);
+   // Neither server keeps the process alive, so a runner that starts one from a
+   // config does not need a teardown hook to exit — and a caller that wants a
+   // deterministic shutdown still has `close()`.
+   proxyServer.unref();
+   controlServer.unref();
+
+   return {
+      url: `http://localhost:${options.listenPort}`,
+      controlUrl: `http://localhost:${controlPort}`,
+      break: async () => run('break'),
+      release: async () => run('release'),
+      status: async () => run('status'),
+      close: async () => {
+         for (const pair of pairs) {
+            pair.browserSocket.destroy();
+            pair.targetSocket.destroy();
+         }
+         pairs.clear();
+         await Promise.all([close(proxyServer), close(controlServer)]);
+      }
+   };
+}
+
+/**
+ * Drives a proxy running in another process, over its control channel.
+ *
+ * This is what a spec uses: Playwright workers are separate processes from the
+ * config that started the proxy.
+ */
+export function flakyNetworkControlClient(controlUrl: string): FlakyNetworkControl {
+   const send = async (command: FlakyNetworkCommand): Promise<string> => {
+      const response = await fetch(`${controlUrl}/${command}`);
+      if (!response.ok) {
+         throw new Error(`flaky-network proxy rejected '${command}': ${response.status}`);
+      }
+      return (await response.text()).trim();
+   };
+   return {
+      break: () => send('break'),
+      release: () => send('release'),
+      status: () => send('status')
+   };
+}
+
+function listen(server: TcpServer | HttpServer, port: number): Promise<void> {
+   return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, () => {
+         server.off('error', reject);
+         resolve();
+      });
+   });
+}
+
+function close(server: TcpServer | HttpServer): Promise<void> {
+   return new Promise(resolve => server.close(() => resolve()));
+}

package/src/testing/playwright/index.ts

@@ -11,6 +11,7 @@
 // `@hydranium/core/testing` barrel) so importing the framework's unit-test
 // helpers never pulls in `@playwright/test` — which is an OPTIONAL peer here.
 export * from './e2e-profiling.js';
+export * from './flaky-network-proxy.js';
 export * from './browser-capture-bridge.js';
 export * from './server-log-capture.js';
 export * from './server-log-fixture.js';