@rstest/browser 0.8.5 → 0.9.1

package/src/hostController.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import { fileURLToPath } from 'node:url';
+import type { Rspack } from '@rstest/core';
 import {
   type BrowserTestRunOptions,
   type BrowserTestRunResult,
@@ -30,14 +31,59 @@ import { type BirpcReturn, createBirpc } from 'birpc';
 import openEditor from 'open-editor';
 import { basename, dirname, join, normalize, relative, resolve } from 'pathe';
 import * as picomatch from 'picomatch';
-import type { BrowserContext, ConsoleMessage, Page } from 'playwright';
 import sirv from 'sirv';
 import { type WebSocket, WebSocketServer } from 'ws';
+import { getHeadlessConcurrency } from './concurrency';
+import {
+  createHostDispatchRouter,
+  type HostDispatchRouterOptions,
+} from './dispatchCapabilities';
+import { createHeadedSerialTaskQueue } from './headedSerialTaskQueue';
+import { createHeadlessLatestRerunScheduler } from './headlessLatestRerunScheduler';
+import { attachHeadlessRunnerTransport } from './headlessTransport';
 import type {
+  BrowserClientMessage,
+  BrowserDispatchHandler,
+  BrowserDispatchRequest,
+  BrowserDispatchResponse,
   BrowserHostConfig,
   BrowserProjectRuntime,
+  BrowserRpcRequest,
+  BrowserViewport,
+  SnapshotRpcRequest,
   TestFileInfo,
 } from './protocol';
+import {
+  DISPATCH_MESSAGE_TYPE,
+  DISPATCH_NAMESPACE_RUNNER,
+  validateBrowserRpcRequest,
+} from './protocol';
+import {
+  type BrowserProvider,
+  type BrowserProviderBrowser,
+  type BrowserProviderContext,
+  type BrowserProviderImplementation,
+  type BrowserProviderPage,
+  getBrowserProviderImplementation,
+} from './providers';
+import {
+  createRunSession,
+  type RunSession,
+  RunSessionLifecycle,
+} from './runSession';
+import { RunnerSessionRegistry } from './sessionRegistry';
+import {
+  loadSourceMapWithCache,
+  normalizeJavaScriptUrl,
+  type SourceMapPayload,
+} from './sourceMap/sourceMapLoader';
+import { resolveBrowserViewportPreset } from './viewportPresets';
+import {
+  isBrowserWatchCliShortcutsEnabled,
+  logBrowserWatchReadyMessage,
+  setupBrowserWatchCliShortcuts,
+} from './watchCliShortcuts';
+import { collectWatchTestFiles, planWatchRerun } from './watchRerunPlanner';
 
 const { createRsbuild, rspack } = rsbuild;
 type RsbuildDevServer = rsbuild.RsbuildDevServer;
@@ -66,16 +112,22 @@ type VirtualModulesPluginInstance = InstanceType<
   (typeof rspack.experiments)['VirtualModulesPlugin']
 >;
 
-type PlaywrightModule = typeof import('playwright');
-type BrowserType = PlaywrightModule['chromium'];
-type BrowserInstance = Awaited<ReturnType<BrowserType['launch']>>;
-
 type BrowserProjectEntries = {
   project: ProjectContext;
   setupFiles: string[];
   testFiles: string[];
 };
 
+type BrowserProviderProject = {
+  rootPath: string;
+  provider: BrowserProvider;
+};
+
+type BrowserLaunchOptions = Pick<
+  ProjectContext['normalizedConfig']['browser'],
+  'provider' | 'browser' | 'headless' | 'port' | 'strictPort'
+>;
+
 /** Payload for test file start event */
 type TestFileStartPayload = {
   testPath: string;
@@ -97,21 +149,30 @@ type FatalPayload = {
   stack?: string;
 };
 
+type ReporterHookArg<THook extends keyof Reporter> = Parameters<
+  NonNullable<Reporter[THook]>
+>[0];
+
+type TestFileReadyPayload = ReporterHookArg<'onTestFileReady'>;
+type TestSuiteStartPayload = ReporterHookArg<'onTestSuiteStart'>;
+type TestSuiteResultPayload = ReporterHookArg<'onTestSuiteResult'>;
+type TestCaseStartPayload = ReporterHookArg<'onTestCaseStart'>;
+
 /** RPC methods exposed by the host (server) to the container (client) */
 type HostRpcMethods = {
   rerunTest: (testFile: string, testNamePattern?: string) => Promise<void>;
   getTestFiles: () => Promise<TestFileInfo[]>;
+  onRunnerFramesReady: (testFiles: string[]) => Promise<void>;
   // Test result callbacks from container
   onTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
   onTestCaseResult: (payload: TestResult) => Promise<void>;
   onTestFileComplete: (payload: TestFileResult) => Promise<void>;
   onLog: (payload: LogPayload) => Promise<void>;
   onFatal: (payload: FatalPayload) => Promise<void>;
-  // Snapshot file operations (for browser mode snapshot support)
-  resolveSnapshotPath: (testPath: string) => Promise<string>;
-  readSnapshotFile: (filepath: string) => Promise<string | null>;
-  saveSnapshotFile: (filepath: string, content: string) => Promise<void>;
-  removeSnapshotFile: (filepath: string) => Promise<void>;
+  // Generic dispatch endpoint used by runner RPC requests.
+  dispatch: (
+    request: BrowserDispatchRequest,
+  ) => Promise<BrowserDispatchResponse>;
 };
 
 /** RPC methods exposed by the container (client) to the host (server) */
@@ -237,15 +298,17 @@ class ContainerRpcManager {
 type BrowserRuntime = {
   rsbuildInstance: RsbuildInstance;
   devServer: RsbuildDevServer;
-  browser: BrowserInstance;
+  browser: BrowserProviderBrowser;
   port: number;
   wsPort: number;
   manifestPath: string;
   tempDir: string;
   manifestPlugin: VirtualModulesPluginInstance;
-  containerPage?: Page;
-  containerContext?: BrowserContext;
+  containerPage?: BrowserProviderPage;
+  containerContext?: BrowserProviderContext;
   setContainerOptions: (options: BrowserHostConfig) => void;
+  // Reserved extension seam for host-side dispatch capabilities.
+  dispatchHandlers: Map<string, BrowserDispatchHandler>;
   wss: WebSocketServer;
   rpcManager?: ContainerRpcManager;
 };
@@ -259,6 +322,8 @@ type WatchContext = {
   lastTestFiles: TestFileInfo[];
   hooksEnabled: boolean;
   cleanupRegistered: boolean;
+  cleanupPromise: Promise<void> | null;
+  closeCliShortcuts: (() => void) | null;
   chunkHashes: Map<string, string>;
   affectedTestFiles: string[];
 };
@@ -268,6 +333,8 @@ const watchContext: WatchContext = {
   lastTestFiles: [],
   hooksEnabled: false,
   cleanupRegistered: false,
+  cleanupPromise: null,
+  closeCliShortcuts: null,
   chunkHashes: new Map(),
   affectedTestFiles: [],
 };
@@ -276,12 +343,128 @@ const watchContext: WatchContext = {
 // Utility Functions
 // ============================================================================
 
+const resolveViewport = (
+  viewport: BrowserViewport | undefined,
+): { width: number; height: number } | null => {
+  if (!viewport) {
+    return null;
+  }
+
+  if (typeof viewport === 'string') {
+    return resolveBrowserViewportPreset(viewport);
+  }
+
+  if (
+    typeof viewport.width === 'number' &&
+    Number.isFinite(viewport.width) &&
+    viewport.width > 0 &&
+    typeof viewport.height === 'number' &&
+    Number.isFinite(viewport.height) &&
+    viewport.height > 0
+  ) {
+    return {
+      width: viewport.width,
+      height: viewport.height,
+    };
+  }
+
+  return null;
+};
+
+const mapViewportByProject = (
+  projects: BrowserProjectRuntime[],
+): Map<string, { width: number; height: number }> => {
+  const map = new Map<string, { width: number; height: number }>();
+  for (const project of projects) {
+    const viewport = resolveViewport(project.viewport);
+    if (viewport) {
+      map.set(project.name, viewport);
+    }
+  }
+  return map;
+};
+
 const ensureProcessExitCode = (code: number): void => {
   if (process.exitCode === undefined || process.exitCode === 0) {
     process.exitCode = code;
   }
 };
 
+const castArray = <T>(arr?: T | T[]): T[] => {
+  if (arr === undefined) {
+    return [];
+  }
+  return Array.isArray(arr) ? arr : [arr];
+};
+
+const applyDefaultWatchOptions = (
+  rspackConfig: Rspack.Configuration,
+  isWatchMode: boolean,
+) => {
+  rspackConfig.watchOptions ??= {};
+
+  if (!isWatchMode) {
+    rspackConfig.watchOptions.ignored = '**/**';
+    return;
+  }
+
+  rspackConfig.watchOptions.ignored = castArray(
+    rspackConfig.watchOptions.ignored || [],
+  ) as string[];
+
+  if (rspackConfig.watchOptions.ignored.length === 0) {
+    rspackConfig.watchOptions.ignored.push('**/.git', '**/node_modules');
+  }
+
+  rspackConfig.output?.path &&
+    rspackConfig.watchOptions.ignored.push(rspackConfig.output.path);
+};
+
+type LazyCompilationModule = {
+  nameForCondition?: () => string | null | undefined;
+};
+
+type BrowserLazyCompilationConfig = {
+  imports: true;
+  entries: false;
+  test?: (module: LazyCompilationModule) => boolean;
+};
+
+export const createBrowserLazyCompilationConfig = (
+  setupFiles: string[],
+): BrowserLazyCompilationConfig => {
+  const eagerSetupFiles = new Set(
+    setupFiles.map((filePath) => normalize(filePath)),
+  );
+
+  if (eagerSetupFiles.size === 0) {
+    return {
+      imports: true,
+      entries: false,
+    };
+  }
+
+  return {
+    imports: true,
+    entries: false,
+    test(module: LazyCompilationModule) {
+      const filePath = module.nameForCondition?.();
+      return !filePath || !eagerSetupFiles.has(normalize(filePath));
+    },
+  };
+};
+
+export const createBrowserRsbuildDevConfig = (isWatchMode: boolean) => {
+  return {
+    // Disable HMR in non-watch mode (tests run once and exit).
+    // Aligns with node mode behavior (packages/core/src/core/rsbuild.ts).
+    hmr: isWatchMode,
+    client: {
+      logLevel: 'error' as const,
+    },
+  };
+};
+
 /**
  * Convert a single glob pattern to RegExp using picomatch
  * Based on Storybook's implementation
@@ -533,6 +716,69 @@ const getBrowserProjects = (context: Rstest): ProjectContext[] => {
   );
 };
 
+const getBrowserLaunchOptions = (
+  project: ProjectContext,
+): BrowserLaunchOptions => ({
+  provider: project.normalizedConfig.browser.provider,
+  browser: project.normalizedConfig.browser.browser,
+  headless: project.normalizedConfig.browser.headless,
+  port: project.normalizedConfig.browser.port,
+  strictPort: project.normalizedConfig.browser.strictPort,
+});
+
+const ensureConsistentBrowserLaunchOptions = (
+  projects: ProjectContext[],
+): BrowserLaunchOptions => {
+  if (projects.length === 0) {
+    throw new Error('No browser-enabled projects found.');
+  }
+
+  const firstProject = projects[0]!;
+  const firstOptions = getBrowserLaunchOptions(firstProject);
+
+  for (const project of projects.slice(1)) {
+    const options = getBrowserLaunchOptions(project);
+    if (
+      options.provider !== firstOptions.provider ||
+      options.browser !== firstOptions.browser ||
+      options.headless !== firstOptions.headless ||
+      options.port !== firstOptions.port ||
+      options.strictPort !== firstOptions.strictPort
+    ) {
+      throw new Error(
+        `Browser launch config mismatch between projects "${firstProject.name}" and "${project.name}". ` +
+          'All browser-enabled projects in one run must share provider/browser/headless/port/strictPort.',
+      );
+    }
+  }
+
+  return firstOptions;
+};
+
+const resolveProviderForTestPath = ({
+  testPath,
+  browserProjects,
+}: {
+  testPath: string;
+  browserProjects: BrowserProviderProject[];
+}): BrowserProvider => {
+  const normalizedTestPath = normalize(testPath);
+  const sortedProjects = [...browserProjects].sort(
+    (a, b) => b.rootPath.length - a.rootPath.length,
+  );
+
+  for (const project of sortedProjects) {
+    if (normalizedTestPath.startsWith(project.rootPath)) {
+      return project.provider;
+    }
+  }
+
+  throw new Error(
+    `Cannot resolve browser provider for test path: ${JSON.stringify(testPath)}. ` +
+      `Known project roots: ${JSON.stringify(sortedProjects.map((p) => p.rootPath))}`,
+  );
+};
+
 const collectProjectEntries = async (
   context: Rstest,
 ): Promise<BrowserProjectEntries[]> => {
@@ -729,21 +975,6 @@ const htmlTemplate = `<!DOCTYPE html>
 </html>
 `;
 
-const fallbackSchedulerHtmlTemplate = `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Rstest Browser Scheduler</title>
-    <script>
-      window.__RSTEST_BROWSER_OPTIONS__ = ${OPTIONS_PLACEHOLDER};
-    </script>
-  </head>
-  <body>
-    <script type="module" src="/container-static/js/scheduler.js"></script>
-  </body>
-</html>
-`;
-
 // Workaround for noisy "removed ..." logs caused by VirtualModulesPlugin.
 // Rsbuild suppresses the removed-file log if all removed paths include "virtual":
 // https://github.com/web-infra-dev/rsbuild/blob/1258fa9dba5c321a4629b591a6dadbd2e26c6963/packages/core/src/createCompiler.ts#L73-L76
@@ -776,27 +1007,39 @@ const destroyBrowserRuntime = async (
     .catch(() => {});
 };
 
-const registerWatchCleanup = (): void => {
-  if (watchContext.cleanupRegistered) {
-    return;
+const cleanupWatchRuntime = (): Promise<void> => {
+  if (watchContext.cleanupPromise) {
+    return watchContext.cleanupPromise;
   }
 
-  const cleanup = async () => {
+  watchContext.cleanupPromise = (async () => {
+    watchContext.closeCliShortcuts?.();
+    watchContext.closeCliShortcuts = null;
+
     if (!watchContext.runtime) {
       return;
     }
+
     await destroyBrowserRuntime(watchContext.runtime);
     watchContext.runtime = null;
-  };
+  })();
+
+  return watchContext.cleanupPromise;
+};
+
+const registerWatchCleanup = (): void => {
+  if (watchContext.cleanupRegistered) {
+    return;
+  }
 
-  for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGTSTP'] as const) {
     process.once(signal, () => {
-      void cleanup();
+      void cleanupWatchRuntime();
     });
   }
 
   process.once('exit', () => {
-    void cleanup();
+    void cleanupWatchRuntime();
   });
 
   watchContext.cleanupRegistered = true;
@@ -831,15 +1074,11 @@ const createBrowserRuntime = async ({
   const containerHtmlTemplate = containerDistPath
     ? await fs.readFile(join(containerDistPath, 'index.html'), 'utf-8')
     : null;
-  const schedulerHtmlTemplate = containerDistPath
-    ? await fs
-        .readFile(join(containerDistPath, 'scheduler.html'), 'utf-8')
-        .catch(() => null)
-    : null;
 
   let injectedContainerHtml: string | null = null;
-  let injectedSchedulerHtml: string | null = null;
   let serializedOptions = 'null';
+  // Reserved extension seam for future browser-side capabilities.
+  const dispatchHandlers = new Map<string, BrowserDispatchHandler>();
 
   const setContainerOptions = (options: BrowserHostConfig): void => {
     serializedOptions = serializeForInlineScript(options);
@@ -849,18 +1088,17 @@ const createBrowserRuntime = async ({
         serializedOptions,
       );
     }
-    injectedSchedulerHtml = (
-      schedulerHtmlTemplate || fallbackSchedulerHtmlTemplate
-    ).replace(OPTIONS_PLACEHOLDER, serializedOptions);
   };
 
-  // Get user Rsbuild config from the first browser project
   const browserProjects = getBrowserProjects(context);
-  const firstProject = browserProjects[0];
-  const userPlugins = firstProject?.normalizedConfig.plugins || [];
-  const userRsbuildConfig = firstProject?.normalizedConfig ?? {};
-  const browserConfig =
-    firstProject?.normalizedConfig.browser ?? context.normalizedConfig.browser;
+  const projectByEnvironmentName = new Map(
+    browserProjects.map((project) => [project.environmentName, project]),
+  );
+  const userPlugins = browserProjects.flatMap(
+    (project) => project.normalizedConfig.plugins || [],
+  );
+  const browserLaunchOptions =
+    ensureConsistentBrowserLaunchOptions(browserProjects);
 
   // Rstest internal aliases that must not be overridden by user config
   const browserRuntimePath = fileURLToPath(
@@ -871,6 +1109,8 @@ const createBrowserRuntime = async ({
     '@rstest/browser-manifest': manifestPath,
     // User test code: import { describe, it } from '@rstest/core'
     '@rstest/core': resolveBrowserFile('client/public.ts'),
+    // User test code: import { page } from '@rstest/browser'
+    '@rstest/browser': resolveBrowserFile('browser.ts'),
     // Browser runtime APIs for entry.ts and public.ts
     // Uses dist file with extractSourceMap to preserve sourcemap chain for inline snapshots
     '@rstest/core/browser-runtime': browserRuntimePath,
@@ -885,16 +1125,14 @@ const createBrowserRuntime = async ({
       plugins: userPlugins,
       server: {
         printUrls: false,
-        port: browserConfig.port ?? 4000,
-        strictPort: browserConfig.strictPort,
-      },
-      dev: {
-        client: {
-          logLevel: 'error',
-        },
+        port: browserLaunchOptions.port ?? 4000,
+        strictPort: browserLaunchOptions.strictPort,
       },
+      dev: createBrowserRsbuildDevConfig(isWatchMode),
       environments: {
-        [firstProject?.environmentName || 'web']: {},
+        ...Object.fromEntries(
+          browserProjects.map((project) => [project.environmentName, {}]),
+        ),
       },
     },
   });
@@ -904,13 +1142,45 @@ const createBrowserRuntime = async ({
     {
       name: 'rstest:browser-user-config',
       setup(api) {
+        // Internal extension entry: register host dispatch handlers without
+        // coupling scheduling to individual capability implementations.
+        (api as { expose?: (name: string, value: unknown) => void }).expose?.(
+          'rstest:browser',
+          {
+            registerDispatchHandler: (
+              namespace: string,
+              handler: BrowserDispatchHandler,
+            ) => {
+              dispatchHandlers.set(namespace, handler);
+            },
+          },
+        );
+
         api.modifyEnvironmentConfig({
-          handler: (config, { mergeEnvironmentConfig }) => {
+          handler: (config, { mergeEnvironmentConfig, name }) => {
+            const project = projectByEnvironmentName.get(name);
+            if (!project) {
+              return config;
+            }
+
+            const userRsbuildConfig = project.normalizedConfig;
+            const setupFiles = Object.values(
+              getSetupFiles(
+                project.normalizedConfig.setupFiles,
+                project.rootPath,
+              ),
+            );
             // Merge order: current config -> userConfig -> rstest required config (highest priority)
             const merged = mergeEnvironmentConfig(config, userRsbuildConfig, {
               resolve: {
                 alias: rstestInternalAliases,
               },
+              source: {
+                define: {
+                  'process.env': 'globalThis[Symbol.for("rstest.env")]',
+                  'import.meta.env': 'globalThis[Symbol.for("rstest.env")]',
+                },
+              },
               output: {
                 target: 'web',
                 // Enable source map for inline snapshot support
@@ -921,13 +1191,13 @@ const createBrowserRuntime = async ({
               tools: {
                 rspack: (rspackConfig) => {
                   rspackConfig.mode = 'development';
-                  rspackConfig.lazyCompilation = {
-                    imports: true,
-                    entries: false,
-                  };
+                  rspackConfig.lazyCompilation =
+                    createBrowserLazyCompilationConfig(setupFiles);
                   rspackConfig.plugins = rspackConfig.plugins || [];
                   rspackConfig.plugins.push(virtualManifestPlugin);
 
+                  applyDefaultWatchOptions(rspackConfig, isWatchMode);
+
                   // Extract and merge sourcemaps from pre-built @rstest/core files
                   // This preserves the sourcemap chain for inline snapshot support
                   // See: https://rspack.dev/config/module-rules#rulesextractsourcemap
@@ -984,8 +1254,8 @@ const createBrowserRuntime = async ({
             if (stats) {
               const projectEntries = await collectProjectEntries(context);
               const entryTestFiles = new Set<string>(
-                projectEntries.flatMap((entry) =>
-                  entry.testFiles.map((f) => normalize(f)),
+                collectWatchTestFiles(projectEntries).map(
+                  (file) => file.testPath,
                 ),
               );
 
@@ -1015,7 +1285,9 @@ const createBrowserRuntime = async ({
   }
 
   // Register coverage plugin for browser mode
-  const coverage = firstProject?.normalizedConfig.coverage;
+  const coverage = browserProjects.find(
+    (project) => project.normalizedConfig.coverage?.enabled,
+  )?.normalizedConfig.coverage;
   if (coverage?.enabled && context.command !== 'list') {
     const { pluginCoverage } = await loadCoverageProvider(
       coverage,
@@ -1109,82 +1381,72 @@ const createBrowserRuntime = async ({
     }
   };
 
-  devServer.middlewares.use(async (req, res, next) => {
-    if (!req.url) {
-      next();
-      return;
-    }
-    const url = new URL(req.url, 'http://localhost');
-    if (url.pathname === '/__open-in-editor') {
-      const file = url.searchParams.get('file');
-      if (!file) {
-        res.statusCode = 400;
-        res.end('Missing file');
+  devServer.middlewares.use(
+    async (req: IncomingMessage, res: ServerResponse, next: () => void) => {
+      if (!req.url) {
+        next();
         return;
       }
-      try {
-        await openEditor([{ file }]);
-        res.statusCode = 204;
-        res.end();
-      } catch (error) {
-        logger.debug(`[Browser UI] Failed to open editor: ${String(error)}`);
-        res.statusCode = 500;
-        res.end('Failed to open editor');
-      }
-      return;
-    }
-    if (url.pathname === '/' || url.pathname === '/scheduler.html') {
-      if (await respondWithDevServerHtml(url, res)) {
+      const url = new URL(req.url, 'http://localhost');
+      if (url.pathname === '/__open-in-editor') {
+        const file = url.searchParams.get('file');
+        if (!file) {
+          res.statusCode = 400;
+          res.end('Missing file');
+          return;
+        }
+        try {
+          await openEditor([{ file }]);
+          res.statusCode = 204;
+          res.end();
+        } catch (error) {
+          logger.debug(`[Browser UI] Failed to open editor: ${String(error)}`);
+          res.statusCode = 500;
+          res.end('Failed to open editor');
+        }
         return;
       }
+      if (url.pathname === '/') {
+        if (await respondWithDevServerHtml(url, res)) {
+          return;
+        }
 
-      if (url.pathname === '/scheduler.html') {
-        res.setHeader('Content-Type', 'text/html');
-        res.end(
-          injectedSchedulerHtml ||
-            (schedulerHtmlTemplate || fallbackSchedulerHtmlTemplate).replace(
-              OPTIONS_PLACEHOLDER,
-              'null',
-            ),
-        );
-        return;
-      }
+        const html =
+          injectedContainerHtml ||
+          containerHtmlTemplate?.replace(OPTIONS_PLACEHOLDER, 'null');
 
-      const html =
-        injectedContainerHtml ||
-        containerHtmlTemplate?.replace(OPTIONS_PLACEHOLDER, 'null');
+        if (html) {
+          res.setHeader('Content-Type', 'text/html');
+          res.end(html);
+          return;
+        }
 
-      if (html) {
-        res.setHeader('Content-Type', 'text/html');
-        res.end(html);
+        res.statusCode = 502;
+        res.end('Container UI is not available.');
         return;
       }
+      if (url.pathname.startsWith('/container-static/')) {
+        if (await proxyDevServerAsset(req, res)) {
+          return;
+        }
 
-      res.statusCode = 502;
-      res.end('Container UI is not available.');
-      return;
-    }
-    if (url.pathname.startsWith('/container-static/')) {
-      if (await proxyDevServerAsset(req, res)) {
+        if (serveContainer) {
+          serveContainer(req, res, next);
+          return;
+        }
+
+        res.statusCode = 502;
+        res.end('Container assets are not available.');
         return;
       }
-
-      if (serveContainer) {
-        serveContainer(req, res, next);
+      if (url.pathname === '/runner.html') {
+        res.setHeader('Content-Type', 'text/html');
+        res.end(htmlTemplate);
         return;
       }
-
-      res.statusCode = 502;
-      res.end('Container assets are not available.');
-      return;
-    }
-    if (url.pathname === '/runner.html') {
-      res.setHeader('Content-Type', 'text/html');
-      res.end(htmlTemplate);
-      return;
-    }
-    next();
-  });
+      next();
+    },
+  );
 
   const { port } = await devServer.listen();
 
@@ -1199,49 +1461,33 @@ const createBrowserRuntime = async ({
   const wsPort = (wss.address() as AddressInfo).port;
   logger.debug(`[Browser UI] WebSocket server started on port ${wsPort}`);
 
-  let browserLauncher: BrowserType;
-  const browserName = browserConfig.browser;
+  const browserName = browserLaunchOptions.browser ?? 'chromium';
   try {
-    const playwright = await import('playwright');
-    browserLauncher = playwright[browserName];
-  } catch (_error) {
-    wss.close();
-    await devServer.close();
-    throw _error;
-  }
-
-  let browser: BrowserInstance;
-  try {
-    browser = await browserLauncher.launch({
-      headless: forceHeadless ?? browserConfig.headless,
-      // Chromium-specific args (ignored by other browsers)
-      args:
-        browserName === 'chromium'
-          ? [
-              '--disable-popup-blocking',
-              '--no-first-run',
-              '--no-default-browser-check',
-            ]
-          : undefined,
+    const providerImplementation = getBrowserProviderImplementation(
+      browserLaunchOptions.provider,
+    );
+    const runtime = await providerImplementation.launchRuntime({
+      browserName,
+      headless: forceHeadless ?? browserLaunchOptions.headless,
     });
+    return {
+      rsbuildInstance,
+      devServer,
+      browser: runtime.browser,
+      port,
+      wsPort,
+      manifestPath,
+      tempDir,
+      manifestPlugin: virtualManifestPlugin,
+      setContainerOptions,
+      dispatchHandlers,
+      wss,
+    };
   } catch (_error) {
     wss.close();
     await devServer.close();
     throw _error;
   }
-
-  return {
-    rsbuildInstance,
-    devServer,
-    browser,
-    port,
-    wsPort,
-    manifestPath,
-    tempDir,
-    manifestPlugin: virtualManifestPlugin,
-    setContainerOptions,
-    wss,
-  };
 };
 
 async function resolveProjectEntries(
@@ -1281,24 +1527,71 @@ export const runBrowserController = async (
   const { skipOnTestRunEnd = false } = options ?? {};
   const buildStart = Date.now();
   const browserProjects = getBrowserProjects(context);
-  const useSchedulerPage = browserProjects.every(
+  const useHeadlessDirect = browserProjects.every(
     (project) => project.normalizedConfig.browser.headless,
   );
 
+  const browserSourceMapCache = new Map<string, SourceMapPayload | null>();
+
+  const isHttpLikeFile = (file: string): boolean => /^https?:\/\//.test(file);
+
+  const resolveBrowserSourcemap = async (sourcePath: string) => {
+    if (!isHttpLikeFile(sourcePath)) {
+      return {
+        handled: false,
+        sourcemap: null,
+      };
+    }
+
+    const normalizedUrl = normalizeJavaScriptUrl(sourcePath);
+    if (!normalizedUrl) {
+      return {
+        handled: true,
+        sourcemap: null,
+      };
+    }
+
+    if (browserSourceMapCache.has(normalizedUrl)) {
+      return {
+        handled: true,
+        sourcemap: browserSourceMapCache.get(normalizedUrl) ?? null,
+      };
+    }
+
+    return {
+      handled: true,
+      sourcemap: await loadSourceMapWithCache({
+        jsUrl: normalizedUrl,
+        cache: browserSourceMapCache,
+      }),
+    };
+  };
+
+  const getBrowserSourcemap = async (
+    sourcePath: string,
+  ): Promise<SourceMapPayload | null> => {
+    const result = await resolveBrowserSourcemap(sourcePath);
+    return result.handled ? result.sourcemap : null;
+  };
+
   /**
    * Build an error BrowserTestRunResult and call onTestRunEnd if needed.
    * Used for early-exit error paths to ensure errors reach the summary report.
    */
   const buildErrorResult = async (
     error: Error,
+    close?: () => Promise<void>,
   ): Promise<BrowserTestRunResult> => {
     const elapsed = Math.max(0, Date.now() - buildStart);
-    const errorResult: BrowserTestRunResult = {
+    const errorResult = {
       results: [],
       testResults: [],
       duration: { totalTime: elapsed, buildTime: elapsed, testTime: 0 },
       hasFailure: true,
       unhandledErrors: [error],
+      getSourcemap: getBrowserSourcemap,
+      resolveSourcemap: resolveBrowserSourcemap,
+      close,
     };
 
     if (!skipOnTestRunEnd) {
@@ -1308,7 +1601,7 @@ export const runBrowserController = async (
           testResults: [],
           duration: errorResult.duration,
           snapshotSummary: context.snapshotManager.summary,
-          getSourcemap: async () => null,
+          getSourcemap: getBrowserSourcemap,
           unhandledErrors: errorResult.unhandledErrors,
         });
       }
@@ -1326,32 +1619,94 @@ export const runBrowserController = async (
     cleanup?: () => Promise<void>,
   ): Promise<BrowserTestRunResult> => {
     ensureProcessExitCode(1);
-    await cleanup?.();
-    return buildErrorResult(toError(error));
+
+    const normalizedError = toError(error);
+
+    if (cleanup && skipOnTestRunEnd) {
+      return buildErrorResult(normalizedError, cleanup);
+    }
+
+    try {
+      return await buildErrorResult(normalizedError);
+    } finally {
+      await cleanup?.();
+    }
+  };
+
+  const collectDeletedTestPaths = (
+    previous: TestFileInfo[],
+    current: TestFileInfo[],
+  ): string[] => {
+    const currentPathSet = new Set(current.map((file) => file.testPath));
+    return previous
+      .map((file) => file.testPath)
+      .filter((testPath) => !currentPathSet.has(testPath));
+  };
+
+  const notifyTestRunStart = async (): Promise<void> => {
+    if (skipOnTestRunEnd) {
+      return;
+    }
+
+    for (const reporter of context.reporters) {
+      await reporter.onTestRunStart?.();
+    }
+  };
+
+  const notifyTestRunEnd = async ({
+    duration,
+    unhandledErrors,
+    filterRerunTestPaths,
+  }: {
+    duration: {
+      totalTime: number;
+      buildTime: number;
+      testTime: number;
+    };
+    unhandledErrors?: Error[];
+    filterRerunTestPaths?: string[];
+  }): Promise<void> => {
+    if (skipOnTestRunEnd) {
+      return;
+    }
+
+    for (const reporter of context.reporters) {
+      await reporter.onTestRunEnd?.({
+        results: context.reporterResults.results,
+        testResults: context.reporterResults.testResults,
+        duration,
+        snapshotSummary: context.snapshotManager.summary,
+        getSourcemap: getBrowserSourcemap,
+        unhandledErrors,
+        filterRerunTestPaths,
+      });
+    }
   };
 
   const containerDevServerEnv = process.env.RSTEST_CONTAINER_DEV_SERVER;
   let containerDevServer: string | undefined;
   let containerDistPath: string | undefined;
 
-  if (containerDevServerEnv) {
-    try {
-      containerDevServer = new URL(containerDevServerEnv).toString();
-      logger.debug(
-        `[Browser UI] Using dev server for container: ${containerDevServer}`,
-      );
-    } catch (error) {
-      const originalError = toError(error);
-      originalError.message = `Invalid RSTEST_CONTAINER_DEV_SERVER value: ${originalError.message}`;
-      return failWithError(originalError);
+  if (!useHeadlessDirect) {
+    if (containerDevServerEnv) {
+      try {
+        containerDevServer = new URL(containerDevServerEnv).toString();
+        logger.debug(
+          `[Browser UI] Using dev server for container: ${containerDevServer}`,
+        );
+      } catch (error) {
+        const originalError = toError(error);
+        originalError.message = `Invalid RSTEST_CONTAINER_DEV_SERVER value: ${originalError.message}`;
+        return failWithError(originalError);
+      }
     }
-  }
 
-  if (!containerDevServer) {
-    try {
-      containerDistPath = resolveContainerDist();
-    } catch (error) {
-      return failWithError(error);
+    if (!containerDevServer) {
+      try {
+        containerDistPath = resolveContainerDist();
+      } catch (error) {
+        return failWithError(error);
+      }
     }
   }
 
@@ -1381,7 +1736,10 @@ export const runBrowserController = async (
     return;
   }
 
+  await notifyTestRunStart();
+
   const isWatchMode = context.command === 'watch';
+  const enableCliShortcuts = isWatchMode && isBrowserWatchCliShortcutsEnabled();
   const tempDir =
     isWatchMode && watchContext.runtime
       ? watchContext.runtime.tempDir
@@ -1402,12 +1760,7 @@ export const runBrowserController = async (
 
   // Track initial test files for watch mode
   if (isWatchMode) {
-    watchContext.lastTestFiles = projectEntries.flatMap((entry) =>
-      entry.testFiles.map((testPath) => ({
-        testPath,
-        projectName: entry.project.name,
-      })),
-    );
+    watchContext.lastTestFiles = collectWatchTestFiles(projectEntries);
   }
 
   let runtime = isWatchMode ? watchContext.runtime : null;
@@ -1440,6 +1793,12 @@ export const runBrowserController = async (
     if (isWatchMode) {
       watchContext.runtime = runtime;
       registerWatchCleanup();
+
+      if (enableCliShortcuts && !watchContext.closeCliShortcuts) {
+        watchContext.closeCliShortcuts = await setupBrowserWatchCliShortcuts({
+          close: cleanupWatchRuntime,
+        });
+      }
     }
   }
 
@@ -1484,23 +1843,827 @@ export const runBrowserController = async (
     rpcTimeout: maxTestTimeoutForRpc,
   };
 
-  runtime.setContainerOptions(hostOptions);
+  const browserProviderProjects: BrowserProviderProject[] = browserProjects.map(
+    (project) => ({
+      rootPath: normalize(project.rootPath),
+      provider: project.normalizedConfig.browser.provider,
+    }),
+  );
+  const implementationByProvider = new Map<
+    BrowserProvider,
+    BrowserProviderImplementation
+  >();
+  for (const browserProject of browserProviderProjects) {
+    if (!implementationByProvider.has(browserProject.provider)) {
+      implementationByProvider.set(
+        browserProject.provider,
+        getBrowserProviderImplementation(browserProject.provider),
+      );
+    }
+  }
 
-  // Track test results from iframes
-  const reporterResults: TestFileResult[] = [];
-  const caseResults: TestResult[] = [];
-  let completedTests = 0;
-  let fatalError: Error | null = null;
+  let activeContainerPage: BrowserProviderPage | null = null;
+  let getHeadlessRunnerPageBySessionId:
+    | ((sessionId: string) => BrowserProviderPage | undefined)
+    | undefined;
+
+  const dispatchBrowserRpcRequest = async ({
+    request,
+    target,
+  }: {
+    request: BrowserRpcRequest;
+    target?: BrowserDispatchRequest['target'];
+  }): Promise<unknown> => {
+    const timeoutFallbackMs = maxTestTimeoutForRpc;
+    const provider = resolveProviderForTestPath({
+      testPath: request.testPath,
+      browserProjects: browserProviderProjects,
+    });
+    const implementation = implementationByProvider.get(provider);
+    if (!implementation) {
+      throw new Error(`Browser provider implementation not found: ${provider}`);
+    }
 
-  // Promise that resolves when all tests complete
-  let resolveAllTests: (() => void) | undefined;
-  const allTestsPromise = new Promise<void>((resolve) => {
-    resolveAllTests = resolve;
-  });
+    const runnerPage = target?.sessionId
+      ? getHeadlessRunnerPageBySessionId?.(target.sessionId)
+      : undefined;
+
+    if (target?.sessionId && !runnerPage) {
+      throw new Error(
+        `Runner page session not found for browser dispatch: ${target.sessionId}`,
+      );
+    }
+
+    if (!runnerPage && !activeContainerPage) {
+      throw new Error('Browser container page is not initialized');
+    }
+
+    try {
+      return await implementation.dispatchRpc({
+        containerPage: runnerPage
+          ? undefined
+          : (activeContainerPage ?? undefined),
+        runnerPage,
+        request,
+        timeoutFallbackMs,
+      });
+    } catch (error) {
+      // birpc serializes thrown Errors as `{}` over JSON; throw a string instead.
+      if (error instanceof Error) {
+        throw error.message;
+      }
+      throw String(error);
+    }
+  };
+
+  runtime.dispatchHandlers.set('browser', async (dispatchRequest) => {
+    const request = validateBrowserRpcRequest(dispatchRequest.args);
+    return dispatchBrowserRpcRequest({
+      request,
+      target: dispatchRequest.target,
+    });
+  });
+
+  runtime.setContainerOptions(hostOptions);
+
+  // Track test results from browser runners
+  const reporterResults: TestFileResult[] = [];
+  const caseResults: TestResult[] = [];
+  let fatalError: Error | null = null;
+
+  const snapshotRpcMethods = {
+    async resolveSnapshotPath(testPath: string): Promise<string> {
+      const snapExtension = '.snap';
+      const resolver =
+        context.normalizedConfig.resolveSnapshotPath ||
+        (() =>
+          join(
+            dirname(testPath),
+            '__snapshots__',
+            `${basename(testPath)}${snapExtension}`,
+          ));
+      return resolver(testPath, snapExtension);
+    },
+    async readSnapshotFile(filepath: string): Promise<string | null> {
+      try {
+        return await fs.readFile(filepath, 'utf-8');
+      } catch {
+        return null;
+      }
+    },
+    async saveSnapshotFile(filepath: string, content: string): Promise<void> {
+      const dir = dirname(filepath);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(filepath, content, 'utf-8');
+    },
+    async removeSnapshotFile(filepath: string): Promise<void> {
+      try {
+        await fs.unlink(filepath);
+      } catch {
+        // ignore if file doesn't exist
+      }
+    },
+  };
+
+  const handleTestFileStart = async (
+    payload: TestFileStartPayload,
+  ): Promise<void> => {
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestFileStart?.({
+          testPath: payload.testPath,
+          tests: [],
+        }),
+      ),
+    );
+  };
+
+  const handleTestFileReady = async (
+    payload: TestFileReadyPayload,
+  ): Promise<void> => {
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestFileReady?.(payload),
+      ),
+    );
+  };
+
+  const handleTestSuiteStart = async (
+    payload: TestSuiteStartPayload,
+  ): Promise<void> => {
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestSuiteStart?.(payload),
+      ),
+    );
+  };
+
+  const handleTestSuiteResult = async (
+    payload: TestSuiteResultPayload,
+  ): Promise<void> => {
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestSuiteResult?.(payload),
+      ),
+    );
+  };
+
+  const handleTestCaseStart = async (
+    payload: TestCaseStartPayload,
+  ): Promise<void> => {
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestCaseStart?.(payload),
+      ),
+    );
+  };
+
+  const handleTestCaseResult = async (payload: TestResult): Promise<void> => {
+    caseResults.push(payload);
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestCaseResult?.(payload),
+      ),
+    );
+  };
+
+  const handleTestFileComplete = async (
+    payload: TestFileResult,
+  ): Promise<void> => {
+    reporterResults.push(payload);
+    context.updateReporterResultState([payload], payload.results);
+    if (payload.snapshotResult) {
+      context.snapshotManager.add(payload.snapshotResult);
+    }
+    await Promise.all(
+      context.reporters.map((reporter) =>
+        (reporter as Reporter).onTestFileResult?.(payload),
+      ),
+    );
+    if (payload.status === 'fail') {
+      ensureProcessExitCode(1);
+    }
+  };
+
+  const handleLog = async (payload: LogPayload): Promise<void> => {
+    const log: UserConsoleLog = {
+      content: payload.content,
+      name: payload.level,
+      testPath: payload.testPath,
+      type: payload.type,
+      trace: payload.trace,
+    };
+    const shouldLog =
+      context.normalizedConfig.onConsoleLog?.(log.content) ?? true;
+    if (shouldLog) {
+      await Promise.all(
+        context.reporters.map((reporter) =>
+          (reporter as Reporter).onUserConsoleLog?.(log),
+        ),
+      );
+    }
+  };
+
+  const handleFatal = async (payload: FatalPayload): Promise<void> => {
+    const error = new Error(payload.message);
+    error.stack = payload.stack;
+    fatalError = error;
+    ensureProcessExitCode(1);
+  };
+
+  const runSnapshotRpc = async (
+    request: SnapshotRpcRequest,
+  ): Promise<unknown> => {
+    switch (request.method) {
+      case 'resolveSnapshotPath':
+        return snapshotRpcMethods.resolveSnapshotPath(request.args.testPath);
+      case 'readSnapshotFile':
+        return snapshotRpcMethods.readSnapshotFile(request.args.filepath);
+      case 'saveSnapshotFile':
+        return snapshotRpcMethods.saveSnapshotFile(
+          request.args.filepath,
+          request.args.content,
+        );
+      case 'removeSnapshotFile':
+        return snapshotRpcMethods.removeSnapshotFile(request.args.filepath);
+      default:
+        return undefined;
+    }
+  };
+
+  const createDispatchRouter = (options?: HostDispatchRouterOptions) => {
+    return createHostDispatchRouter({
+      routerOptions: options,
+      runnerCallbacks: {
+        onTestFileStart: handleTestFileStart,
+        onTestFileReady: handleTestFileReady,
+        onTestSuiteStart: handleTestSuiteStart,
+        onTestSuiteResult: handleTestSuiteResult,
+        onTestCaseStart: handleTestCaseStart,
+        onTestCaseResult: handleTestCaseResult,
+        onTestFileComplete: handleTestFileComplete,
+        onLog: handleLog,
+        onFatal: handleFatal,
+      },
+      runSnapshotRpc,
+      extensionHandlers: runtime.dispatchHandlers,
+      onDuplicateNamespace: (namespace) => {
+        logger.debug(
+          `[Dispatch] Skip registering dispatch namespace "${namespace}" because it is already reserved`,
+        );
+      },
+    });
+  };
+
+  if (useHeadlessDirect) {
+    // Session-based scheduling path: lifecycle + session index + dispatch routing.
+    type ActiveHeadlessRun = RunSession & {
+      contexts: Set<BrowserProviderContext>;
+    };
+
+    const viewportByProject = mapViewportByProject(projectRuntimeConfigs);
+    const runLifecycle = new RunSessionLifecycle<ActiveHeadlessRun>();
+    const sessionRegistry = new RunnerSessionRegistry();
+    getHeadlessRunnerPageBySessionId = (sessionId) => {
+      return sessionRegistry.getById(sessionId)?.page;
+    };
+    let dispatchRequestCounter = 0;
+
+    const nextDispatchRequestId = (namespace: string): string => {
+      return `${namespace}-${++dispatchRequestCounter}`;
+    };
+
+    const closeContextSafely = async (
+      browserContext: BrowserProviderContext,
+    ): Promise<void> => {
+      try {
+        await browserContext.close();
+      } catch {
+        // ignore
+      }
+    };
+
+    const cancelRun = async (
+      run: ActiveHeadlessRun,
+      waitForDone = true,
+    ): Promise<void> => {
+      await runLifecycle.cancel(run, {
+        waitForDone,
+        onCancel: async (session) => {
+          await Promise.all(
+            Array.from(session.contexts).map((browserContext) =>
+              closeContextSafely(browserContext),
+            ),
+          );
+        },
+      });
+    };
+
+    const dispatchRouter = createDispatchRouter({
+      isRunTokenStale: (runToken) => runLifecycle.isTokenStale(runToken),
+      onStale: (request) => {
+        if (request.namespace === DISPATCH_NAMESPACE_RUNNER) {
+          logger.debug(
+            `[Headless] Dropped stale message "${request.method}" for ${request.target?.testFile ?? 'unknown'}`,
+          );
+        }
+      },
+    });
+
+    const dispatchRunnerMessage = async (
+      run: ActiveHeadlessRun,
+      file: TestFileInfo,
+      sessionId: string,
+      message: BrowserClientMessage,
+    ): Promise<void> => {
+      const response = await dispatchRouter.dispatch({
+        requestId: nextDispatchRequestId('runner'),
+        runToken: run.token,
+        namespace: DISPATCH_NAMESPACE_RUNNER,
+        method: message.type,
+        args: 'payload' in message ? message.payload : undefined,
+        target: {
+          sessionId,
+          testFile: file.testPath,
+          projectName: file.projectName,
+        },
+      });
+
+      if (response.stale) {
+        return;
+      }
+
+      if (response.error) {
+        throw new Error(response.error);
+      }
+    };
+
+    const runSingleFile = async (
+      run: ActiveHeadlessRun,
+      file: TestFileInfo,
+    ): Promise<void> => {
+      if (run.cancelled || runLifecycle.isTokenStale(run.token)) {
+        return;
+      }
+
+      const viewport = viewportByProject.get(file.projectName);
+      const browserContext = await browser.newContext({
+        viewport: viewport ?? null,
+      });
+      run.contexts.add(browserContext);
+
+      let page: BrowserProviderPage | null = null;
+      let sessionId: string | null = null;
+      let settled = false;
+      let resolveDone: (() => void) | null = null;
+
+      const markDone = (): void => {
+        if (!settled) {
+          settled = true;
+          resolveDone?.();
+        }
+      };
+
+      const donePromise = new Promise<void>((resolve) => {
+        resolveDone = resolve;
+      });
+
+      const projectRuntime = projectRuntimeConfigs.find(
+        (project) => project.name === file.projectName,
+      );
+      const perFileTimeoutMs =
+        (projectRuntime?.runtimeConfig.testTimeout ?? maxTestTimeoutForRpc) +
+        30_000;
+
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+      try {
+        page = await browserContext.newPage();
+
+        const session = sessionRegistry.register({
+          testFile: file.testPath,
+          projectName: file.projectName,
+          runToken: run.token,
+          mode: 'headless-page',
+          context: browserContext,
+          page,
+        });
+        sessionId = session.id;
+
+        await attachHeadlessRunnerTransport(page, {
+          onDispatchMessage: async (message) => {
+            try {
+              await dispatchRunnerMessage(run, file, session.id, message);
+              if (
+                message.type === 'file-complete' ||
+                message.type === 'complete'
+              ) {
+                markDone();
+              } else if (message.type === 'fatal') {
+                markDone();
+                await cancelRun(run, false);
+              }
+            } catch (error) {
+              const formatted = toError(error);
+              await handleFatal({
+                message: formatted.message,
+                stack: formatted.stack,
+              });
+              markDone();
+              await cancelRun(run, false);
+            }
+          },
+          onDispatchRpc: async (request) => {
+            return dispatchRouter.dispatch({
+              ...request,
+              runToken: run.token,
+              target: {
+                sessionId: session.id,
+                testFile: file.testPath,
+                projectName: file.projectName,
+                ...request.target,
+              },
+            });
+          },
+        });
+
+        const inlineOptions: BrowserHostConfig = {
+          ...hostOptions,
+          testFile: file.testPath,
+          runId: `${run.token}:${session.id}`,
+        };
+        const serializedOptions = serializeForInlineScript(inlineOptions);
+        await page.addInitScript(
+          `window.__RSTEST_BROWSER_OPTIONS__ = ${serializedOptions};`,
+        );
+
+        await page.goto(`http://localhost:${port}/runner.html`, {
+          waitUntil: 'load',
+        });
+
+        const timeoutPromise = new Promise<'timeout'>((resolve) => {
+          timeoutId = setTimeout(() => resolve('timeout'), perFileTimeoutMs);
+        });
+
+        const state = await Promise.race([
+          donePromise.then(() => 'done' as const),
+          timeoutPromise,
+          run.cancelSignal.then(() => 'cancelled' as const),
+        ]);
+
+        if (state === 'cancelled') {
+          return;
+        }
+
+        if (
+          state === 'timeout' &&
+          runLifecycle.isTokenActive(run.token) &&
+          !run.cancelled
+        ) {
+          await handleFatal({
+            message: `Test execution timeout after ${perFileTimeoutMs / 1000}s for ${file.testPath}.`,
+          });
+          await cancelRun(run, false);
+        }
+      } catch (error) {
+        if (runLifecycle.isTokenActive(run.token) && !run.cancelled) {
+          const formatted = toError(error);
+          await handleFatal({
+            message: formatted.message,
+            stack: formatted.stack,
+          });
+          await cancelRun(run, false);
+        }
+      } finally {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        if (page) {
+          try {
+            await page.close();
+          } catch {
+            // ignore
+          }
+        }
+        if (sessionId) {
+          sessionRegistry.deleteById(sessionId);
+        }
+        run.contexts.delete(browserContext);
+        await closeContextSafely(browserContext);
+      }
+    };
+
+    const runFilesWithPool = async (files: TestFileInfo[]): Promise<void> => {
+      if (files.length === 0) {
+        return;
+      }
+
+      const previous = runLifecycle.activeSession;
+      if (previous) {
+        await cancelRun(previous);
+      }
+
+      const run = runLifecycle.createSession((token) => ({
+        ...createRunSession(token),
+        contexts: new Set<BrowserProviderContext>(),
+      }));
+
+      const queue = [...files];
+      const concurrency = getHeadlessConcurrency(context, queue.length);
+
+      const worker = async (): Promise<void> => {
+        while (
+          queue.length > 0 &&
+          !run.cancelled &&
+          runLifecycle.isTokenActive(run.token)
+        ) {
+          const next = queue.shift();
+          if (!next) {
+            return;
+          }
+          await runSingleFile(run, next);
+        }
+      };
+
+      run.done = Promise.all(
+        Array.from(
+          { length: Math.min(queue.length, Math.max(concurrency, 1)) },
+          () => worker(),
+        ),
+      ).then(() => {});
+
+      await run.done;
+      runLifecycle.clearIfActive(run);
+    };
+
+    const latestRerunScheduler = createHeadlessLatestRerunScheduler<
+      TestFileInfo,
+      ActiveHeadlessRun
+    >({
+      getActiveRun: () => runLifecycle.activeSession,
+      isRunCancelled: (run) => run.cancelled,
+      invalidateActiveRun: () => {
+        runLifecycle.invalidateActiveToken();
+      },
+      interruptActiveRun: async (run) => {
+        await cancelRun(run, false);
+      },
+      runFiles: async (files) => {
+        await notifyTestRunStart();
+
+        const rerunStartTime = Date.now();
+        const fatalErrorBeforeRun = fatalError;
+        let rerunError: Error | undefined;
+
+        try {
+          await runFilesWithPool(files);
+        } catch (error) {
+          rerunError = toError(error);
+          throw error;
+        } finally {
+          const testTime = Math.max(0, Date.now() - rerunStartTime);
+          const rerunFatalError =
+            fatalError && fatalError !== fatalErrorBeforeRun
+              ? fatalError
+              : undefined;
+          await notifyTestRunEnd({
+            duration: {
+              totalTime: testTime,
+              buildTime: 0,
+              testTime,
+            },
+            filterRerunTestPaths: files.map((file) => file.testPath),
+            unhandledErrors: rerunError
+              ? [rerunError]
+              : rerunFatalError
+                ? [rerunFatalError]
+                : undefined,
+          });
+          logBrowserWatchReadyMessage(enableCliShortcuts);
+        }
+      },
+      onError: async (error) => {
+        const formatted = toError(error);
+        await handleFatal({
+          message: formatted.message,
+          stack: formatted.stack,
+        });
+      },
+      onInterrupt: (run) => {
+        logger.debug(
+          `[Headless] Interrupting active run token ${run.token} before scheduling latest rerun`,
+        );
+      },
+    });
+
+    const testStart = Date.now();
+    await runFilesWithPool(allTestFiles);
+    const testTime = Date.now() - testStart;
+
+    if (isWatchMode) {
+      triggerRerun = async () => {
+        const newProjectEntries = await collectProjectEntries(context);
+        const rerunPlan = planWatchRerun({
+          projectEntries: newProjectEntries,
+          previousTestFiles: watchContext.lastTestFiles,
+          affectedTestFiles: watchContext.affectedTestFiles,
+        });
+        watchContext.affectedTestFiles = [];
+
+        if (rerunPlan.filesChanged) {
+          const deletedTestPaths = collectDeletedTestPaths(
+            watchContext.lastTestFiles,
+            rerunPlan.currentTestFiles,
+          );
+          if (deletedTestPaths.length > 0) {
+            context.updateReporterResultState([], [], deletedTestPaths);
+          }
+          watchContext.lastTestFiles = rerunPlan.currentTestFiles;
+          if (rerunPlan.currentTestFiles.length === 0) {
+            await latestRerunScheduler.enqueueLatest([]);
+            logger.log(
+              color.cyan('No browser test files remain after update.\n'),
+            );
+            logBrowserWatchReadyMessage(enableCliShortcuts);
+            return;
+          }
+
+          logger.log(
+            color.cyan(
+              `Test file set changed, re-running ${rerunPlan.currentTestFiles.length} file(s)...\n`,
+            ),
+          );
+          void latestRerunScheduler.enqueueLatest(rerunPlan.currentTestFiles);
+          return;
+        }
+
+        if (rerunPlan.affectedTestFiles.length === 0) {
+          logger.log(
+            color.cyan(
+              'No affected browser test files detected, skipping re-run.\n',
+            ),
+          );
+          logBrowserWatchReadyMessage(enableCliShortcuts);
+          return;
+        }
+
+        logger.log(
+          color.cyan(
+            `Re-running ${rerunPlan.affectedTestFiles.length} affected test file(s)...\n`,
+          ),
+        );
+        void latestRerunScheduler.enqueueLatest(rerunPlan.affectedTestFiles);
+      };
+    }
+
+    const closeHeadlessRuntime = !isWatchMode
+      ? async () => {
+          sessionRegistry.clear();
+          await destroyBrowserRuntime(runtime);
+        }
+      : undefined;
+
+    if (fatalError) {
+      return failWithError(fatalError, closeHeadlessRuntime);
+    }
+
+    const duration = {
+      totalTime: buildTime + testTime,
+      buildTime,
+      testTime,
+    };
+
+    context.updateReporterResultState(reporterResults, caseResults);
+
+    const isFailure = reporterResults.some(
+      (result: TestFileResult) => result.status === 'fail',
+    );
+    if (isFailure) {
+      ensureProcessExitCode(1);
+    }
+
+    const result = {
+      results: reporterResults,
+      testResults: caseResults,
+      duration,
+      hasFailure: isFailure,
+      getSourcemap: getBrowserSourcemap,
+      resolveSourcemap: resolveBrowserSourcemap,
+      close: skipOnTestRunEnd ? closeHeadlessRuntime : undefined,
+    };
+
+    if (!skipOnTestRunEnd) {
+      try {
+        await notifyTestRunEnd({ duration });
+      } finally {
+        await closeHeadlessRuntime?.();
+      }
+    }
+
+    if (isWatchMode && triggerRerun) {
+      watchContext.hooksEnabled = true;
+      logBrowserWatchReadyMessage(enableCliShortcuts);
+    }
+
+    return result;
+  }
+
+  let currentTestFiles = allTestFiles;
+  const RUNNER_FRAMES_READY_TIMEOUT_MS = 30_000;
+  let currentRunnerFramesSignature: string | null = null;
+  const runnerFramesWaiters = new Map<string, Set<() => void>>();
+
+  const createTestFilesSignature = (testFiles: readonly string[]): string => {
+    return JSON.stringify(testFiles.map((testFile) => normalize(testFile)));
+  };
+
+  const markRunnerFramesReady = (testFiles: string[]): void => {
+    const signature = createTestFilesSignature(testFiles);
+    currentRunnerFramesSignature = signature;
+    const waiters = runnerFramesWaiters.get(signature);
+    if (!waiters) {
+      return;
+    }
+    runnerFramesWaiters.delete(signature);
+    for (const waiter of waiters) {
+      waiter();
+    }
+  };
+
+  const waitForRunnerFramesReady = async (
+    testFiles: readonly string[],
+  ): Promise<void> => {
+    const signature = createTestFilesSignature(testFiles);
+    if (currentRunnerFramesSignature === signature) {
+      return;
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const waiters =
+        runnerFramesWaiters.get(signature) ?? new Set<() => void>();
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+      const cleanup = () => {
+        const currentWaiters = runnerFramesWaiters.get(signature);
+        if (!currentWaiters) {
+          return;
+        }
+        currentWaiters.delete(onReady);
+        if (currentWaiters.size === 0) {
+          runnerFramesWaiters.delete(signature);
+        }
+      };
+
+      const onReady = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        cleanup();
+        resolve();
+      };
+
+      timeoutId = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            `Timed out waiting for headed runner frames to be ready for ${testFiles.length} file(s).`,
+          ),
+        );
+      }, RUNNER_FRAMES_READY_TIMEOUT_MS);
+
+      waiters.add(onReady);
+      runnerFramesWaiters.set(signature, waiters);
+
+      if (currentRunnerFramesSignature === signature) {
+        onReady();
+      }
+    });
+  };
+
+  const getTestFileInfo = (testFile: string): TestFileInfo => {
+    const normalizedTestFile = normalize(testFile);
+    const fileInfo = currentTestFiles.find(
+      (file) => file.testPath === normalizedTestFile,
+    );
+    if (!fileInfo) {
+      throw new Error(`Unknown browser test file: ${JSON.stringify(testFile)}`);
+    }
+    return fileInfo;
+  };
+
+  const getHeadedPerFileTimeoutMs = (file: TestFileInfo): number => {
+    const projectRuntime = projectRuntimeConfigs.find(
+      (project) => project.name === file.projectName,
+    );
+    return (
+      (projectRuntime?.runtimeConfig.testTimeout ?? maxTestTimeoutForRpc) +
+      30_000
+    );
+  };
 
   // Open a container page for user to view (reuse in watch mode)
-  let containerContext: BrowserContext;
-  let containerPage: Page;
+  let containerContext: BrowserProviderContext;
+  let containerPage: BrowserProviderPage;
   let isNewPage = false;
 
   if (isWatchMode && runtime.containerPage && runtime.containerContext) {
@@ -1515,11 +2678,11 @@ export const runBrowserController = async (
     containerPage = await containerContext.newPage();
 
     // Prevent popup windows from being created
-    containerPage.on('popup', async (popup: Page) => {
+    containerPage.on('popup', async (popup: BrowserProviderPage) => {
       await popup.close().catch(() => {});
     });
 
-    containerContext.on('page', async (page: Page) => {
+    containerContext.on('page', async (page: BrowserProviderPage) => {
       if (page !== containerPage) {
         await page.close().catch(() => {});
       }
@@ -1531,18 +2694,52 @@ export const runBrowserController = async (
     }
 
     // Forward browser console to terminal
-    containerPage.on('console', (msg: ConsoleMessage) => {
+    containerPage.on('console', (msg) => {
       const text = msg.text();
-      if (
-        text.startsWith('[Container]') ||
-        text.startsWith('[Runner]') ||
-        text.startsWith('[Scheduler]')
-      ) {
+      if (text.startsWith('[Container]') || text.startsWith('[Runner]')) {
         logger.log(color.gray(`[Browser Console] ${text}`));
       }
     });
   }
 
+  activeContainerPage = containerPage;
+
+  const dispatchRouter = createDispatchRouter();
+  const headedReloadQueue = createHeadedSerialTaskQueue();
+  let enqueueHeadedReload = async (
+    _file: TestFileInfo,
+    _testNamePattern?: string,
+  ): Promise<void> => {
+    throw new Error('Headed reload queue is not initialized');
+  };
+
+  const reloadTestFileWithTimeout = async (
+    file: TestFileInfo,
+    testNamePattern?: string,
+  ): Promise<void> => {
+    const timeoutMs = getHeadedPerFileTimeoutMs(file);
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+      await Promise.race([
+        rpcManager.reloadTestFile(file.testPath, testNamePattern),
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => {
+            reject(
+              new Error(
+                `Headed test execution timeout after ${timeoutMs / 1000}s for ${file.testPath}.`,
+              ),
+            );
+          }, timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  };
+
   // Create RPC methods that can access test state variables
   const createRpcMethods = (): HostRpcMethods => ({
     async rerunTest(testFile: string, testNamePattern?: string) {
@@ -1554,105 +2751,32 @@ export const runBrowserController = async (
           `\nRe-running test: ${displayPath}${testNamePattern ? ` (pattern: ${testNamePattern})` : ''}\n`,
         ),
       );
-      await rpcManager.reloadTestFile(testFile, testNamePattern);
+      await enqueueHeadedReload(getTestFileInfo(testFile), testNamePattern);
     },
     async getTestFiles() {
-      return allTestFiles;
+      return currentTestFiles;
+    },
+    async onRunnerFramesReady(testFiles: string[]) {
+      markRunnerFramesReady(testFiles);
     },
     async onTestFileStart(payload: TestFileStartPayload) {
-      await Promise.all(
-        context.reporters.map((reporter) =>
-          (reporter as Reporter).onTestFileStart?.({
-            testPath: payload.testPath,
-            tests: [],
-          }),
-        ),
-      );
+      await handleTestFileStart(payload);
     },
     async onTestCaseResult(payload: TestResult) {
-      caseResults.push(payload);
-      await Promise.all(
-        context.reporters.map((reporter) =>
-          (reporter as Reporter).onTestCaseResult?.(payload),
-        ),
-      );
+      await handleTestCaseResult(payload);
     },
     async onTestFileComplete(payload: TestFileResult) {
-      reporterResults.push(payload);
-      if (payload.snapshotResult) {
-        context.snapshotManager.add(payload.snapshotResult);
-      }
-      await Promise.all(
-        context.reporters.map((reporter) =>
-          (reporter as Reporter).onTestFileResult?.(payload),
-        ),
-      );
-
-      completedTests++;
-      if (completedTests >= allTestFiles.length && resolveAllTests) {
-        resolveAllTests();
-      }
+      await handleTestFileComplete(payload);
     },
     async onLog(payload: LogPayload) {
-      const log: UserConsoleLog = {
-        content: payload.content,
-        name: payload.level,
-        testPath: payload.testPath,
-        type: payload.type,
-        trace: payload.trace,
-      };
-
-      // Check onConsoleLog filter
-      const shouldLog =
-        context.normalizedConfig.onConsoleLog?.(log.content) ?? true;
-
-      if (shouldLog) {
-        await Promise.all(
-          context.reporters.map((reporter) =>
-            (reporter as Reporter).onUserConsoleLog?.(log),
-          ),
-        );
-      }
+      await handleLog(payload);
     },
     async onFatal(payload: FatalPayload) {
-      fatalError = new Error(payload.message);
-      fatalError.stack = payload.stack;
-      if (resolveAllTests) {
-        resolveAllTests();
-      }
-    },
-    // Snapshot file operations
-    async resolveSnapshotPath(testPath: string) {
-      const snapExtension = '.snap';
-      const resolver =
-        context.normalizedConfig.resolveSnapshotPath ||
-        // test/index.ts -> test/__snapshots__/index.ts.snap
-        (() =>
-          join(
-            dirname(testPath),
-            '__snapshots__',
-            `${basename(testPath)}${snapExtension}`,
-          ));
-      return resolver(testPath, snapExtension);
-    },
-    async readSnapshotFile(filepath: string) {
-      try {
-        return await fs.readFile(filepath, 'utf-8');
-      } catch {
-        return null;
-      }
+      await handleFatal(payload);
     },
-    async saveSnapshotFile(filepath: string, content: string) {
-      const dir = dirname(filepath);
-      await fs.mkdir(dir, { recursive: true });
-      await fs.writeFile(filepath, content, 'utf-8');
-    },
-    async removeSnapshotFile(filepath: string) {
-      try {
-        await fs.unlink(filepath);
-      } catch {
-        // ignore if file doesn't exist
-      }
+    async dispatch(request: BrowserDispatchRequest) {
+      // Headed/container path now shares the same dispatch contract as headless.
+      return dispatchRouter.dispatch(request);
     },
   });
 
@@ -1678,13 +2802,7 @@ export const runBrowserController = async (
 
   // Only navigate on first creation
   if (isNewPage) {
-    const pagePath = useSchedulerPage ? '/scheduler.html' : '/';
-    if (useSchedulerPage) {
-      const serializedOptions = serializeForInlineScript(hostOptions);
-      await containerPage.addInitScript(
-        `window.__RSTEST_BROWSER_OPTIONS__ = ${serializedOptions};`,
-      );
-    }
+    const pagePath = '/';
     await containerPage.goto(`http://localhost:${port}${pagePath}`, {
       waitUntil: 'load',
     });
@@ -1696,31 +2814,33 @@ export const runBrowserController = async (
     );
   }
 
-  // Wait for all tests to complete
-  // Calculate total timeout based on config: max testTimeout * file count + buffer
-  const maxTestTimeout = Math.max(
-    ...browserProjects.map((p) => p.normalizedConfig.testTimeout ?? 5000),
-  );
-  const totalTimeoutMs = maxTestTimeout * allTestFiles.length + 30_000;
-
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
-  const testTimeout = new Promise<void>((resolve) => {
-    timeoutId = setTimeout(() => {
-      logger.log(
-        color.yellow(
-          `\nTest execution timeout after ${totalTimeoutMs / 1000}s. ` +
-            `Completed: ${completedTests}/${allTestFiles.length}\n`,
-        ),
-      );
-      resolve();
-    }, totalTimeoutMs);
-  });
+  enqueueHeadedReload = async (
+    file: TestFileInfo,
+    testNamePattern?: string,
+  ): Promise<void> => {
+    return headedReloadQueue.enqueue(async () => {
+      if (fatalError) {
+        return;
+      }
+      await reloadTestFileWithTimeout(file, testNamePattern);
+    });
+  };
 
   const testStart = Date.now();
-  await Promise.race([allTestsPromise, testTimeout]);
+  try {
+    await waitForRunnerFramesReady(
+      currentTestFiles.map((file) => file.testPath),
+    );
 
-  if (timeoutId) {
-    clearTimeout(timeoutId);
+    for (const file of currentTestFiles) {
+      await enqueueHeadedReload(file);
+      if (fatalError) {
+        break;
+      }
+    }
+  } catch (error) {
+    fatalError = fatalError ?? toError(error);
+    ensureProcessExitCode(1);
   }
 
   const testTime = Date.now() - testStart;
@@ -1729,63 +2849,96 @@ export const runBrowserController = async (
   if (isWatchMode) {
     triggerRerun = async () => {
       const newProjectEntries = await collectProjectEntries(context);
-      // Normalize paths to posix format for cross-platform compatibility
-      const currentTestFiles: TestFileInfo[] = newProjectEntries.flatMap(
-        (entry) =>
-          entry.testFiles.map((testPath) => ({
-            testPath: normalize(testPath),
-            projectName: entry.project.name,
-          })),
-      );
+      const rerunPlan = planWatchRerun({
+        projectEntries: newProjectEntries,
+        previousTestFiles: watchContext.lastTestFiles,
+        affectedTestFiles: watchContext.affectedTestFiles,
+      });
+      watchContext.affectedTestFiles = [];
 
-      // Compare test files by serializing to JSON for deep comparison
-      const serialize = (files: TestFileInfo[]) =>
-        JSON.stringify(
-          files.map((f) => `${f.projectName}:${f.testPath}`).sort(),
+      if (rerunPlan.filesChanged) {
+        const deletedTestPaths = collectDeletedTestPaths(
+          watchContext.lastTestFiles,
+          rerunPlan.currentTestFiles,
         );
-
-      const filesChanged =
-        serialize(currentTestFiles) !== serialize(watchContext.lastTestFiles);
-
-      if (filesChanged) {
-        watchContext.lastTestFiles = currentTestFiles;
+        if (deletedTestPaths.length > 0) {
+          context.updateReporterResultState([], [], deletedTestPaths);
+        }
+        watchContext.lastTestFiles = rerunPlan.currentTestFiles;
+        currentTestFiles = rerunPlan.currentTestFiles;
         await rpcManager.notifyTestFileUpdate(currentTestFiles);
+        await waitForRunnerFramesReady(
+          currentTestFiles.map((file) => file.testPath),
+        );
       }
 
-      const affectedFiles = watchContext.affectedTestFiles;
-      watchContext.affectedTestFiles = [];
-
-      if (affectedFiles.length > 0) {
+      if (rerunPlan.normalizedAffectedTestFiles.length > 0) {
         logger.log(
           color.cyan(
-            `Re-running ${affectedFiles.length} affected test file(s)...\n`,
+            `Re-running ${rerunPlan.normalizedAffectedTestFiles.length} affected test file(s)...\n`,
           ),
         );
-        for (const testFile of affectedFiles) {
-          await rpcManager.reloadTestFile(testFile);
+        await notifyTestRunStart();
+
+        const rerunStartTime = Date.now();
+        const fatalErrorBeforeRun = fatalError;
+        let rerunError: Error | undefined;
+
+        try {
+          for (const testFile of rerunPlan.normalizedAffectedTestFiles) {
+            await enqueueHeadedReload(getTestFileInfo(testFile));
+          }
+        } catch (error) {
+          rerunError = toError(error);
+          throw error;
+        } finally {
+          const testTime = Math.max(0, Date.now() - rerunStartTime);
+          const rerunFatalError =
+            fatalError && fatalError !== fatalErrorBeforeRun
+              ? fatalError
+              : undefined;
+          await notifyTestRunEnd({
+            duration: {
+              totalTime: testTime,
+              buildTime: 0,
+              testTime,
+            },
+            filterRerunTestPaths: rerunPlan.normalizedAffectedTestFiles,
+            unhandledErrors: rerunError
+              ? [rerunError]
+              : rerunFatalError
+                ? [rerunFatalError]
+                : undefined,
+          });
+          logBrowserWatchReadyMessage(enableCliShortcuts);
         }
-      } else if (!filesChanged) {
+      } else if (!rerunPlan.filesChanged) {
         logger.log(color.cyan('Tests will be re-executed automatically\n'));
+        logBrowserWatchReadyMessage(enableCliShortcuts);
+      } else {
+        logBrowserWatchReadyMessage(enableCliShortcuts);
       }
     };
   }
 
-  if (!isWatchMode) {
-    try {
-      await containerPage.close();
-    } catch {
-      // ignore
-    }
-    try {
-      await containerContext.close();
-    } catch {
-      // ignore
-    }
-    await destroyBrowserRuntime(runtime);
-  }
+  const closeContainerRuntime = !isWatchMode
+    ? async () => {
+        try {
+          await containerPage.close();
+        } catch {
+          // ignore
+        }
+        try {
+          await containerContext.close();
+        } catch {
+          // ignore
+        }
+        await destroyBrowserRuntime(runtime);
+      }
+    : undefined;
 
   if (fatalError) {
-    return failWithError(fatalError);
+    return failWithError(fatalError, closeContainerRuntime);
   }
 
   const duration = {
@@ -1803,32 +2956,28 @@ export const runBrowserController = async (
     ensureProcessExitCode(1);
   }
 
-  const result: BrowserTestRunResult = {
+  const result = {
     results: reporterResults,
     testResults: caseResults,
     duration,
     hasFailure: isFailure,
+    getSourcemap: getBrowserSourcemap,
+    resolveSourcemap: resolveBrowserSourcemap,
+    close: skipOnTestRunEnd ? closeContainerRuntime : undefined,
   };
 
-  // Only call onTestRunEnd if not skipped (for unified reporter output)
   if (!skipOnTestRunEnd) {
-    for (const reporter of context.reporters) {
-      await reporter.onTestRunEnd?.({
-        results: context.reporterResults.results,
-        testResults: context.reporterResults.testResults,
-        duration,
-        snapshotSummary: context.snapshotManager.summary,
-        getSourcemap: async () => null,
-      });
+    try {
+      await notifyTestRunEnd({ duration });
+    } finally {
+      await closeContainerRuntime?.();
     }
   }
 
   // Enable watch hooks AFTER initial test run to avoid duplicate runs
   if (isWatchMode && triggerRerun) {
     watchContext.hooksEnabled = true;
-    logger.log(
-      color.cyan('\nWatch mode enabled - will re-run tests on file changes\n'),
-    );
+    logBrowserWatchReadyMessage(enableCliShortcuts);
   }
 
   return result;
@@ -1887,6 +3036,7 @@ export const listBrowserTests = async (
     manifestPath,
     entries: projectEntries,
   });
+  const browserProjects = getBrowserProjects(context);
 
   // Create a simplified browser runtime for collect mode
   let runtime: BrowserRuntime;
@@ -1902,9 +3052,14 @@ export const listBrowserTests = async (
       forceHeadless: true, // Always use headless for list command
     });
   } catch (error) {
+    const providers = [
+      ...new Set(
+        browserProjects.map((p) => p.normalizedConfig.browser.provider),
+      ),
+    ];
     logger.error(
       color.red(
-        'Failed to load Playwright. Please install "playwright" to use browser mode.',
+        `Failed to initialize browser provider runtime (${providers.join(', ')}).`,
       ),
       error,
     );
@@ -1915,7 +3070,6 @@ export const listBrowserTests = async (
 
   // Get browser projects for runtime config
   // Normalize projectRoot to posix format for cross-platform compatibility
-  const browserProjects = getBrowserProjects(context);
   const projectRuntimeConfigs: BrowserProjectRuntime[] = browserProjects.map(
     (project: ProjectContext) => ({
       name: project.name,
@@ -1961,7 +3115,7 @@ export const listBrowserTests = async (
 
   // Expose dispatch function for browser client to send messages
   await page.exposeFunction(
-    '__rstest_dispatch__',
+    DISPATCH_MESSAGE_TYPE,
     (message: { type: string; payload?: unknown }) => {
       switch (message.type) {
         case 'collect-result': {