Method launch

browse/src/browser-manager.ts:340–420

()

  }

  async launch() {
    // ─── Extension Support ────────────────────────────────────
    // BROWSE_EXTENSIONS_DIR points to an unpacked Chrome extension directory.
    // Extensions only work in headed mode, so we use an off-screen window.
    const extensionsDir = process.env.BROWSE_EXTENSIONS_DIR;
    const { STEALTH_LAUNCH_ARGS, buildGStackLaunchArgs } = await import('./stealth');
    const launchArgs: string[] = [...STEALTH_LAUNCH_ARGS, ...buildGStackLaunchArgs()];
    let useHeadless = true;

    // Docker/CI/root: Chromium sandbox requires unprivileged user namespaces which
    // are typically disabled in containers and are never available for the root
    // user on Linux. Detect all three cases and add --no-sandbox automatically.
    const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
    if (process.env.CI || process.env.CONTAINER || isRoot) {
      launchArgs.push('--no-sandbox');
    }

    if (extensionsDir) {
      // Skip --load-extension when running against a custom Chromium build that
      // already bakes the extension in (e.g., GBrowser / GStack Browser.app).
      // Loading it twice causes a ServiceWorkerState::SetWorkerId DCHECK crash.
      if (!isCustomChromium()) {
        launchArgs.push(
          `--disable-extensions-except=${extensionsDir}`,
          `--load-extension=${extensionsDir}`,
        );
      }
      launchArgs.push('--window-position=-9999,-9999', '--window-size=1,1');
      useHeadless = false; // extensions require headed mode; off-screen window simulates headless
      console.log(`[browse] Extensions loaded from: ${extensionsDir}`);
    }

    this.browser = await chromium.launch({
      headless: useHeadless,
      // On Windows, Chromium's sandbox fails when the server is spawned through
      // the Bun→Node process chain (GitHub #276). Disable it — local daemon
      // browsing user-specified URLs has marginal sandbox benefit. Also disabled
      // on Linux root/CI/container, where the sandbox requires unprivileged user
      // namespaces that aren't available.
      chromiumSandbox: shouldEnableChromiumSandbox(),
      ...(launchArgs.length > 0 ? { args: launchArgs } : {}),
      ...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
    });

    // Chromium disconnect → distinguish clean user-quit from crash. Both
    // events look identical to Playwright (one 'disconnected' fires), but
    // the underlying ChildProcess exit code separates them:
    //   exitCode === 0  → clean quit (user Cmd+Q on macOS, normal shutdown)
    //   exitCode !== 0  → crash, signal-kill, or OOM
    // Process supervisors (gbrowser's gbd) consume our exit code: code 0
    // means "user wanted this, don't restart"; non-zero means "crash, please
    // bring me back." Without this distinction every Cmd+Q gets treated as
    // a crash and the user-visible window keeps respawning.
    this.browser.on('disconnected', () => {
      void handleChromiumDisconnect(this.browser);
    });

    const contextOptions: BrowserContextOptions = {