@ultimat3/testing 24.0.0 → 25.1.0

package/src/cdp-e2e-session.ts

@@ -35,11 +35,25 @@ export interface CdpE2eSessionOptions {
   readonly acceptLanguage?: string | undefined;
 }
 
-const POLL_MS = 50;
+/** What a page reports to its own code — the state a test's next `fetch` runs under. */
+const ON_LINE = 'navigator.onLine';
+
+/**
+ * Answers `true` at once when the page already reads `online`, else on the `online`/`offline`
+ * event that flips it. The read and the `addEventListener` run in ONE task, so the event cannot
+ * land between them. `false` only when the event came and the state still disagrees: ask again.
+ */
+const readsOnLine = (online: boolean): string => {
+  const reads = `${ON_LINE} === ${String(online)}`;
+  const flip = online ? 'online' : 'offline';
+  return `${reads} || new Promise((resolve) => addEventListener('${flip}', () => resolve(${reads}), { once: true }))`;
+};
+
+const member = (from: unknown, key: string): unknown =>
+  typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
 
 const field = (from: unknown, key: string): string | undefined => {
-  const value =
-    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
+  const value = member(from, key);
   return typeof value === 'string' ? value : undefined;
 };
 
@@ -55,6 +69,8 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
   const send = connection.send.bind(connection);
   const sessions = new Set<string>();
   const pages = new Map<string, string>(); // targetId → sessionId
+  // targetId → the `newTab()` waiting for that tab to be published.
+  const published = new Map<string, (session: string) => void>();
   const scripts: string[] = [];
   const sockets: string[] = [];
   const requests: string[] = [];
@@ -137,6 +153,7 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
       const targetId = field(info, 'targetId');
       if (type === 'page' && targetId !== undefined && sessions.has(session)) {
         pages.set(targetId, session);
+        published.get(targetId)?.(session);
       }
     })();
   });
@@ -147,6 +164,86 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
     flatten: true,
   });
 
+  /** Settles `true` on `event` from `session` and `false` at `deadline`, whichever is first. */
+  const nextEvent = (event: string, session: string, deadline: number) => {
+    let heard: () => void = () => undefined;
+    const arrived = new Promise<void>((resolve) => {
+      heard = resolve;
+    });
+    const off = connection.on(event, (_params, on) => {
+      if (on === session) heard();
+    });
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return {
+      /** Subscribed when created, so an event that lands before this is awaited still counts. */
+      wait: (): Promise<boolean> =>
+        Promise.race([
+          arrived.then(() => true),
+          new Promise<boolean>((resolve) => {
+            timer = setTimeout(() => resolve(false), Math.max(0, deadline - performance.now()));
+          }),
+        ]),
+      close: (): void => {
+        off();
+        clearTimeout(timer);
+      },
+    };
+  };
+
+  /**
+   * Whether one page came to read `navigator.onLine === online` before `deadline`. The page itself
+   * says when — the evaluated promise resolves on the event that flips it, `awaitPromise` holds the
+   * reply until then — so nothing is polled and nothing sleeps. A navigation destroys the context
+   * the promise lived in and refuses the call; the page is asked again in the document that
+   * replaces it, once Chrome announces that document's context.
+   */
+  const pageReads = async (session: string, online: boolean, deadline: number) => {
+    for (;;) {
+      const remaining = deadline - performance.now();
+      if (remaining <= 0) return false;
+      const context = nextEvent('Runtime.executionContextCreated', session, deadline);
+      try {
+        const answer = await send(
+          'Runtime.evaluate',
+          { expression: readsOnLine(online), returnByValue: true, awaitPromise: true },
+          session,
+          remaining,
+        );
+        const value = member(member(answer.result, 'result'), 'value');
+        if (value === true) return true;
+        // `false`: the event fired and the state disagrees, so the next ask awaits the next one.
+        // Anything else is a page that could not run the read — the same as a refusal, below.
+        if (value !== false && !(await context.wait())) return false;
+      } catch (error) {
+        if (error instanceof CdpTimeoutError) return false;
+        if (!(await context.wait())) return false;
+      } finally {
+        context.close();
+      }
+    }
+  };
+
+  // #572. `offline()` SENDS the condition, and the renderer applies it when it gets to it: a `fetch`
+  // on the caller's next line raced that on a slow runner and went through under a switch the test
+  // had already thrown. So the switch is thrown when every page READS the state, and not before —
+  // never a fixed sleep, which is either too long everywhere or too short on the runner that
+  // matters. Bounded by the load budget, because a page mid-navigation answers only once it lands;
+  // a page that never reads it is a timeout naming the page, never a resolve the test trusts.
+  const confirmed = async (online: boolean): Promise<void> => {
+    const deadline = performance.now() + options.loadTimeoutMs;
+    const open = [...pageSessions].filter((session) => sessions.has(session));
+    const answers = await Promise.all(
+      open.map(async (session) => [session, await pageReads(session, online, deadline)] as const),
+    );
+    const waiting = answers.filter(([, reads]) => !reads).map(([session]) => session);
+    if (waiting.length > 0) {
+      throw new CdpTimeoutError({
+        method: `${ON_LINE} === ${String(online)} in page session ${waiting.join(', ')}`,
+        timeoutMs: options.loadTimeoutMs,
+      });
+    }
+  };
+
   const offline = async (enabled: boolean): Promise<void> => {
     cut = enabled;
     // Sequential, and a session that has gone away is dropped rather than taking the rest down.
@@ -168,17 +265,28 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
       await toggled.catch((error: unknown) => refused.push(error));
     }
     if (refused.length > 0) throw refused[0];
+    await confirmed(!enabled);
   };
 
-  const attached = async (targetId: string): Promise<string> => {
-    for (let waited = 0; waited < options.loadTimeoutMs; waited += POLL_MS) {
-      const session = pages.get(targetId);
-      if (session !== undefined) return session;
-      await Bun.sleep(POLL_MS);
-    }
-    throw new CdpTimeoutError({
-      method: `Target.attachedToTarget for tab ${targetId}`,
-      timeoutMs: options.loadTimeoutMs,
+  /** The tab's session once it is published — told by the attach itself, never polled for. */
+  const attached = (targetId: string): Promise<string> => {
+    const session = pages.get(targetId);
+    if (session !== undefined) return Promise.resolve(session);
+    return new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        published.delete(targetId);
+        reject(
+          new CdpTimeoutError({
+            method: `Target.attachedToTarget for tab ${targetId}`,
+            timeoutMs: options.loadTimeoutMs,
+          }),
+        );
+      }, options.loadTimeoutMs);
+      published.set(targetId, (ready) => {
+        clearTimeout(timer);
+        published.delete(targetId);
+        resolve(ready);
+      });
     });
   };
 

package/src/cdp-errors.ts

@@ -22,27 +22,43 @@ export class CdpBrowserMissingError extends UltimateError {
 
 /** One start of the browser that ended without an answer — what `cdp-launch-attempt.ts` reports. */
 export interface CdpLaunchAttempt {
-  /** `deadline`: alive and silent for `waitedMs`. `closed`: its pipe ended before any answer. */
-  readonly why: 'deadline' | 'closed';
+  /**
+   * `deadline`: alive and silent for `waitedMs`. `closed`: its wire ended, or its dial was
+   * refused, before any answer. `spawn`: the binary could not be started at all — it never ran.
+   */
+  readonly why: 'deadline' | 'closed' | 'spawn';
   readonly waitedMs: number;
   /** The code it exited with on its own, or `null` when the launcher had to kill it. */
   readonly exitCode: number | null;
   /** The last lines it wrote to stderr; empty when it wrote none. */
   readonly stderr: string;
+  /**
+   * What the LAUNCHER saw end the attempt, rendered: the refused dial and its endpoint, the call
+   * that timed out, the spawn's own error. Absent on a record that predates it.
+   */
+  readonly detail?: string | undefined;
 }
 
 const HAND_FLAGS =
   '--headless=new --no-sandbox --disable-dev-shm-usage --disable-gpu --remote-debugging-port=0 about:blank';
 
+const endedText = (attempt: CdpLaunchAttempt): string => {
+  const after = `after ${String(attempt.waitedMs)}ms`;
+  if (attempt.why === 'spawn') return 'could not be started';
+  if (attempt.why === 'deadline')
+    return `no answer inside ${String(attempt.waitedMs)}ms, so it was killed`;
+  return attempt.exitCode === null
+    ? `its DevTools connection ended ${after} without an answer, and it was killed`
+    : `exited with code ${String(attempt.exitCode)} ${after} without answering`;
+};
+
 const attemptText = (attempt: CdpLaunchAttempt, index: number): string => {
-  const ended =
-    attempt.why === 'deadline'
-      ? `no answer inside ${String(attempt.waitedMs)}ms, so it was killed`
-      : attempt.exitCode === null
-        ? `closed its DevTools pipe after ${String(attempt.waitedMs)}ms without answering, and was killed`
-        : `exited with code ${String(attempt.exitCode)} after ${String(attempt.waitedMs)}ms without answering`;
+  const saw =
+    attempt.detail === undefined || attempt.detail === ''
+      ? ''
+      : `: ${renderCauseValue(attempt.detail)}`;
   const said = attempt.stderr === '' ? 'it printed nothing' : renderCauseValue(attempt.stderr);
-  return `launch ${String(index + 1)}: ${ended}; stderr: ${said}`;
+  return `launch ${String(index + 1)}: ${endedText(attempt)}${saw}; stderr: ${said}`;
 };
 
 /**

package/src/cdp-launch-attempt.ts

@@ -2,26 +2,34 @@
 // first DevTools answer, and on no answer reap it (killed, awaited, profile removed) and say why.
 // Which binary, which flags and how many starts is `cdp-launch.ts`.
 
-// why: Bun exposes no recursive-remove and no temp-root primitive, so the throwaway profile
-// directory this launcher must create and delete needs both.
-import { mkdtempSync, rmSync } from 'node:fs';
-// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
-import { tmpdir } from 'node:os';
-// why: Bun exposes no path-join primitive.
-import { join } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import type { CdpConnection } from './cdp-connection';
-import { cdpConnectOver } from './cdp-connection';
 import type { CdpLaunchAttempt } from './cdp-errors';
 import { CdpTimeoutError } from './cdp-errors';
-import { pipeTransport } from './cdp-pipe';
+import { throwawayProfile } from './cdp-launch-profile';
+import { CLOSE_GRACE_MS, killTree } from './cdp-launch-reap';
+import type { CdpWire } from './cdp-launch-wire';
+import { pipeConnection, portConnection, wireStdio } from './cdp-launch-wire';
+
+export { CLOSE_GRACE_MS } from './cdp-launch-reap';
+
+/**
+ * The longest `LaunchedBrowser.close()` is DESIGNED to take: SIGTERM's grace, SIGKILL's, the group
+ * reap, then the profile's removal — four `CLOSE_GRACE_MS`, each step bounded by its own. A hook
+ * that closes a browser and gives it less is killed by Bun mid-close, and when that hook is the
+ * run's last the process exits with the profile half-removed: the `Default/Cache` tree the leaked
+ * `x-e2e-chrome-*` directories held.
+ */
+export const LAUNCHED_CLOSE_MS = 4 * CLOSE_GRACE_MS;
 
 export interface LaunchedBrowser {
-  /** The browser's own CDP connection, over its debugging pipe. Already answering. */
+  /** The browser's own CDP connection, over its debugging pipe or port. Already answering. */
   readonly connection: CdpConnection;
   /**
    * THE close, idempotent, and awaited by every caller: the connection closed, SIGTERM, SIGKILL
-   * after `CLOSE_GRACE_MS`, then the browser's whole process group killed and the profile removed —
-   * bounded at three graces. A promise because a Chrome still shutting down competes with the next
+   * after `CLOSE_GRACE_MS`, then the browser's whole process group killed and, only then, the
+   * profile removed — bounded at `LAUNCHED_CLOSE_MS`. On Windows, which has no SIGTERM to grant grace to, the process TREE
+   * is killed outright (`killTree`) and awaited. A promise because a Chrome still shutting down competes with the next
    * launch on a 4-CPU runner, and its children re-create a profile removed before they are gone.
    */
   close(): Promise<void>;
@@ -31,6 +39,10 @@ export interface LaunchAttemptOptions {
   readonly executable: string;
   /** What the process is started with, given the profile directory this attempt made for it. */
   readonly flags: (profileDir: string) => readonly string[];
+  /** Which wire the flags opened — `cdp-launch-wire.ts`. */
+  readonly wire: CdpWire;
+  /** Whose process rules the reap follows. Defaults to this process's platform. */
+  readonly platform?: string | undefined;
   /** Every call's deadline AFTER the first. */
   readonly timeoutMs: number;
   /** The first call's deadline: how long a cold start may take. */
@@ -83,93 +95,91 @@ function stderrTail(stream: ReadableStream<Uint8Array>): {
  */
 const FAILURE_DRAIN_MS = 1_000;
 
-/** How long a closed Chrome gets to exit on SIGTERM before it is killed outright. */
-export const CLOSE_GRACE_MS = 5_000;
+/**
+ * The longest a FAILED attempt spends after its deadline before the next can start: the drain a
+ * browser that hung up gets, the bounded close (`LAUNCHED_CLOSE_MS`), then the stderr drain. A
+ * caller's hook deadline adds this per attempt.
+ */
+export const LAUNCH_REAP_MS = FAILURE_DRAIN_MS + LAUNCHED_CLOSE_MS + FAILURE_DRAIN_MS;
 
 const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
   Promise.race([work, Bun.sleep(ms)]);
 
-const GROUP_POLL_MS = 10;
-
-/**
- * Kill whatever is left of the browser's process group and wait until the group is EMPTY — the
- * condition, asked of the kernel, not a pause: signal 0 to a group with no member throws. Bounded
- * by `CLOSE_GRACE_MS` for a container whose init never reaps a zombie.
- */
-async function reapGroup(pgid: number): Promise<void> {
-  try {
-    process.kill(-pgid, 'SIGKILL');
-    for (let looks = CLOSE_GRACE_MS / GROUP_POLL_MS; looks > 0; looks -= 1) {
-      await Bun.sleep(GROUP_POLL_MS);
-      process.kill(-pgid, 0);
-    }
-  } catch {
-    // ESRCH: nothing is left in the group, which is the answer being waited for.
-  }
-}
-
 /**
  * Start the browser once and answer when it has answered one CDP call. With a pipe there is no
  * "DevTools listening" line to wait for — the first reply IS the readiness signal.
  */
 export async function launchAttempt(options: LaunchAttemptOptions): Promise<LaunchAttemptResult> {
-  const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
-  const removeProfile = (): void => {
-    try {
-      rmSync(profileDir, { recursive: true, force: true });
-    } catch {
-      // A throwaway directory that will not go is litter, never the launch's or the close's verdict.
-    }
-  };
+  const platform = options.platform ?? process.platform;
+  const profile = throwawayProfile();
+  const profileDir = profile.path;
   const began = performance.now();
-  const child = Bun.spawn([options.executable, ...options.flags(profileDir)], {
-    // Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies and events.
-    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
-    // Its own process GROUP, so the zygote, GPU and network processes can be reaped with it
-    // (`reapGroup`). It still ends with this process: Chrome exits when its fd 3 closes.
-    detached: true,
-  });
-  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
-  const [, , , toBrowser, fromBrowser] = child.stdio as unknown as readonly number[];
-  const sink = Bun.file(toBrowser ?? -1).writer();
-  const connection = cdpConnectOver(
-    pipeTransport({
-      write: (bytes) => {
-        sink.write(bytes);
-        void sink.flush();
-      },
-      read: Bun.file(fromBrowser ?? -1).stream(),
-      end: () => {
-        void Promise.resolve(sink.end()).catch(() => undefined);
+  let child: ReturnType<typeof spawnBrowser>;
+  try {
+    child = spawnBrowser(options, profileDir, platform);
+  } catch (error) {
+    // A binary that cannot be started at all — not there, not executable, not an executable FORMAT
+    // this OS runs (a `#!` script on Windows). Bun throws from `spawn`, synchronously, and that
+    // throw escaped as a bare ENOENT where every other way a launch fails is X_CDP_LAUNCH_FAILED.
+    await profile.remove(undefined, CLOSE_GRACE_MS);
+    return {
+      ok: false,
+      failure: {
+        why: 'spawn',
+        waitedMs: 0,
+        exitCode: null,
+        stderr: '',
+        detail: renderThrowable(error),
       },
-    }),
-    options.timeoutMs,
-  );
+      reaped: true,
+    };
+  }
+  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
+  let connection: CdpConnection | undefined =
+    options.wire === 'pipe' ? pipeConnection(child.stdio, options.timeoutMs) : undefined;
   let exiting: Promise<void> | undefined;
   const close = (): Promise<void> => {
     exiting ??= (async () => {
-      connection.close();
-      child.kill();
-      removeProfile();
-      const exited =
-        (await within(
-          CLOSE_GRACE_MS,
-          child.exited.then(() => true),
-        )) === true;
-      if (!exited) {
-        child.kill('SIGKILL');
+      // Read while the browser still runs: a clean exit unlinks it, a killed one never does.
+      const singleton = profile.singletonDir();
+      connection?.close();
+      if (platform === 'win32') {
+        // No SIGTERM to grant grace to: a kill on Windows is TerminateProcess, and taking the
+        // browser alone would orphan the children that hold the profile's files open.
+        await killTree(child.pid, platform);
         await within(CLOSE_GRACE_MS, child.exited);
+      } else {
+        child.kill();
+        const exited =
+          (await within(
+            CLOSE_GRACE_MS,
+            child.exited.then(() => true),
+          )) === true;
+        if (!exited) {
+          child.kill('SIGKILL');
+          await within(CLOSE_GRACE_MS, child.exited);
+        }
+        await killTree(child.pid, platform);
       }
-      await reapGroup(child.pid);
-      // Again, now that nothing is writing: Chrome's network process outlives the browser process
-      // and flushes into the profile, re-creating a directory removed a moment before. Measured on
-      // Chrome 150, 30 launches each: left behind 6 and 12 times without the group reap, 0 with.
-      removeProfile();
+      // Only now, with the tree gone: removed under a live browser, the profile is re-created by
+      // its shutdown — the network process flushes its cache, the browser writes its prefs — and
+      // a close cut short there leaves exactly that tree. Measured on Chrome 150, 30 launches
+      // each: left behind 6 and 12 times without the group reap, 0 with.
+      await profile.remove(singleton, CLOSE_GRACE_MS);
     })();
     return exiting;
   };
   try {
-    await connection.send('Browser.getVersion', {}, undefined, options.launchTimeoutMs);
+    // The pipe needs no wait to exist; the port is not known until the browser writes it down, and
+    // finding it spends the same launch deadline the first answer does.
+    connection ??= await portConnection({
+      profileDir,
+      exited: () => child.exitCode !== null || child.signalCode !== null,
+      deadlineMs: options.launchTimeoutMs,
+      timeoutMs: options.timeoutMs,
+    });
+    const left = Math.max(1, options.launchTimeoutMs - (performance.now() - began));
+    await connection.send('Browser.getVersion', {}, undefined, left);
     return { ok: true, browser: { connection, close } };
   } catch (error) {
     const why = error instanceof CdpTimeoutError ? 'deadline' : 'closed';
@@ -185,8 +195,30 @@ export async function launchAttempt(options: LaunchAttemptOptions): Promise<Laun
     await within(FAILURE_DRAIN_MS, tail.drained);
     return {
       ok: false,
-      failure: { why, waitedMs, exitCode, stderr: tail.lastLines() },
+      // `detail`: the error itself. Without it a refused dial after "DevTools listening" read as a
+      // browser that hung up (seen on windows), and nothing said which step had failed.
+      failure: {
+        why,
+        waitedMs,
+        exitCode,
+        stderr: tail.lastLines(),
+        detail: renderThrowable(error),
+      },
       reaped: child.exitCode !== null || child.signalCode !== null,
     };
   }
 }
+
+/**
+ * The process, on its own process GROUP on POSIX so the zygote, GPU and network processes are
+ * reaped with it (`killTree`). It still ends with this process on the pipe wire: Chrome exits when
+ * its fd 3 closes. Windows has no group to make — `detached` there is a console flag — so not.
+ */
+function spawnBrowser(options: LaunchAttemptOptions, profileDir: string, platform: string) {
+  // Spread into a fresh tuple: Bun's `stdio` type takes a mutable tuple, never a readonly one.
+  const [stdin, stdout, stderr, ...extra] = wireStdio(options.wire);
+  return Bun.spawn([options.executable, ...options.flags(profileDir)], {
+    stdio: [stdin, stdout, stderr, ...extra],
+    detached: platform !== 'win32',
+  });
+}

package/src/cdp-launch-candidates.ts

@@ -0,0 +1,62 @@
+// One responsibility: WHERE a Chrome is installed, per platform — the ordered list `findChrome`
+// probes when `CHROME_PATH` names none. Which binary wins and how it starts is `cdp-launch.ts`.
+
+// why: a Windows candidate is spelled with `\` whatever OS computes the list (a test, or the
+// Linux runner asserting it), and only node:path's win32 half joins that way. Bun has no path API.
+import { win32 } from 'node:path';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** What GitHub-hosted `ubuntu-latest` ships, which lets CI run the browser suite with no download. */
+const LINUX: readonly string[] = [
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+];
+
+const set = (value: string | undefined): string | undefined =>
+  value === undefined || value === '' ? undefined : value;
+
+/**
+ * Chrome under each root an installer uses — machine-wide 64- and 32-bit, then per-user — then
+ * Edge, which is Chromium, speaks the same DevTools protocol and is on every Windows 10 and 11. A
+ * root the environment does not name falls back to its fixed default; a per-user root has none, so
+ * it is not guessed at.
+ */
+const windows = (env: Env): readonly string[] => {
+  const programFiles = set(env['ProgramFiles']) ?? 'C:\\Program Files';
+  const programFilesX86 = set(env['ProgramFiles(x86)']) ?? 'C:\\Program Files (x86)';
+  const localAppData = set(env['LOCALAPPDATA']);
+  const chromeRoots = [programFiles, programFilesX86, ...(localAppData ? [localAppData] : [])];
+  return [
+    ...chromeRoots.map((root) => win32.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe')),
+    // x86 first for Edge: it is where the Windows image installs it, 64-bit or not.
+    ...[programFilesX86, programFiles].map((root) =>
+      win32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+    ),
+  ];
+};
+
+const MAC_CHROME = 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+
+/** The app bundles' executables: system-wide, then the per-user `~/Applications` an admin-less install uses. */
+const mac = (env: Env): readonly string[] => {
+  const home = set(env['HOME']);
+  return [
+    `/${MAC_CHROME}`,
+    ...(home ? [`${home}/${MAC_CHROME}`] : []),
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ];
+};
+
+/**
+ * Where a Chrome is on `platform`, in the order worth trying. Any platform that is neither Windows
+ * nor macOS gets the Linux paths — the BSDs install to the same names when they install at all.
+ */
+export function chromeCandidates(platform: string, env: Env): readonly string[] {
+  if (platform === 'win32') return windows(env);
+  if (platform === 'darwin') return mac(env);
+  return LINUX;
+}

package/src/cdp-launch-profile.ts

@@ -0,0 +1,106 @@
+// One responsibility: the throwaway profile a launch hands Chrome, and its removal — after every
+// process of the browser is gone, retried while something re-creates it, bounded — together with
+// the singleton-socket directory Chrome makes BESIDE it in the temp root.
+
+// why: Bun exposes no temp-root, recursive-remove or readlink primitive; the profile needs all three.
+import { existsSync, mkdtempSync, readdirSync, readlinkSync, rmdirSync, rmSync } from 'node:fs';
+// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path-join primitive.
+import { basename, dirname, join } from 'node:path';
+
+/**
+ * How long a removed profile is watched for coming back before it counts as gone. Chrome's late
+ * writers are the network service flushing its disk cache and the browser's atomic preference
+ * write (`Default/.com.google.Chrome.XXXXXX`) — the exact tree the leaked profiles held. Removal
+ * waits for the process tree first, so the look is for what the tree kill cannot see: a process
+ * outside the group (Chrome's crashpad handler calls `setsid`), and on Windows a child `taskkill`
+ * has not finished ending when it returns.
+ */
+export const PROFILE_SETTLE_MS = 50;
+
+/**
+ * What Chrome's ProcessSingleton puts in its socket directory, and nothing else. The directory is
+ * `<temp>/com.google.Chrome.XXXXXX` (Chromium: `org.chromium.Chromium.…`), linked from the profile's
+ * `SingletonSocket`, and a browser that does not shut down cleanly never removes it: measured, one
+ * left in the temp root per launch — 444 of them beside 146 leaked profiles.
+ */
+const SINGLETON_FILES: ReadonlySet<string> = new Set([
+  'SingletonSocket',
+  'SingletonCookie',
+  'SingletonLock',
+]);
+
+export interface ThrowawayProfile {
+  readonly path: string;
+  /**
+   * Where the browser's singleton socket lives, read off the profile's own link. Asked BEFORE the
+   * browser is signalled: a browser that exits cleanly removes the link first, and one killed
+   * leaves the directory with nothing in the profile pointing at it.
+   */
+  singletonDir(): string | undefined;
+  /**
+   * Remove the profile — and `singleton`, when it holds Chrome's singleton files and nothing else —
+   * and answer once neither has come back for `PROFILE_SETTLE_MS`, or at `deadlineMs`. Never throws:
+   * a directory that will not go is litter, never the close's verdict.
+   */
+  remove(singleton: string | undefined, deadlineMs: number): Promise<void>;
+}
+
+const quietly = (work: () => void): void => {
+  try {
+    work();
+  } catch {
+    // Already gone, or held open past the deadline: the loop's next look decides which.
+  }
+};
+
+/**
+ * Only a directory whose every entry is a singleton file is Chrome's to have made: a link that
+ * points anywhere else is somebody's directory, and is left alone.
+ */
+function isSingletonDir(dir: string): boolean {
+  try {
+    return readdirSync(dir).every((entry) => SINGLETON_FILES.has(entry));
+  } catch {
+    return false;
+  }
+}
+
+/** File by file, then a plain `rmdir` — never a recursive remove of a path read off a link. */
+function removeSingleton(dir: string): void {
+  for (const entry of SINGLETON_FILES) quietly(() => rmSync(join(dir, entry), { force: true }));
+  quietly(() => rmdirSync(dir));
+}
+
+/** A fresh profile directory under the temp root, named so a leak is recognisable as ours. */
+export function throwawayProfile(root: string = tmpdir()): ThrowawayProfile {
+  const path = mkdtempSync(join(root, 'x-e2e-chrome-'));
+  return {
+    path,
+    singletonDir() {
+      try {
+        const target = readlinkSync(join(path, 'SingletonSocket'));
+        return basename(target) === 'SingletonSocket' ? dirname(target) : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    async remove(singleton, deadlineMs) {
+      const until = performance.now() + deadlineMs;
+      const owned = singleton !== undefined && isSingletonDir(singleton) ? singleton : undefined;
+      const present = (): boolean => existsSync(path) || (owned !== undefined && existsSync(owned));
+      do {
+        quietly(() => rmSync(path, { recursive: true, force: true }));
+        if (owned !== undefined) removeSingleton(owned);
+        if (present()) {
+          await Bun.sleep(PROFILE_SETTLE_MS / 5);
+          continue;
+        }
+        // Gone NOW is not gone: the look after the settle is what a late writer fails.
+        await Bun.sleep(PROFILE_SETTLE_MS);
+        if (!present()) return;
+      } while (performance.now() < until);
+    },
+  };
+}