From 5c1533a0563d6ee38d0305b822446d0281a43648 Mon Sep 17 00:00:00 2001
From: fi3ework <fi3ework@gmail.com>
Date: Sun, 8 Feb 2026 23:51:53 +0800
Subject: [PATCH] feat(browser): add lightweight scheduler page for headless
 mode

---
 e2e/browser-mode/basic.test.ts          |   6 +-
 packages/browser-ui/rsbuild.config.ts   |   1 +
 packages/browser-ui/src/core/channel.ts |  81 +++++++
 packages/browser-ui/src/core/runtime.ts |  24 ++
 packages/browser-ui/src/hooks/useRpc.ts |  59 +----
 packages/browser-ui/src/main.tsx        | 228 +++++++------------
 packages/browser-ui/src/scheduler.ts    | 288 ++++++++++++++++++++++++
 packages/browser-ui/src/types.ts        |  47 +++-
 packages/browser/src/hostController.ts  | 114 ++++++++--
 9 files changed, 617 insertions(+), 231 deletions(-)
 create mode 100644 packages/browser-ui/src/core/channel.ts
 create mode 100644 packages/browser-ui/src/core/runtime.ts
 create mode 100644 packages/browser-ui/src/scheduler.ts

diff --git a/e2e/browser-mode/basic.test.ts b/e2e/browser-mode/basic.test.ts
index cad1ce1d6..8a19a5239 100644
--- a/e2e/browser-mode/basic.test.ts
+++ b/e2e/browser-mode/basic.test.ts
@@ -34,14 +34,16 @@ describe('browser mode - basic', () => {
 
     await expectExecSuccess();
     expect(cli.stdout).toMatch(/Test Files.*passed/);
+    expect(cli.stdout).toContain('/scheduler.html');
   });
 
-  it('should exit with code 0 when tests pass', async () => {
+  it('should run headed mode without scheduler page and exit with code 0', async () => {
     const { cli } = await runBrowserCli('basic', {
-      args: ['tests/dom.test.ts'],
+      args: ['--browser.headless', 'false', 'tests/dom.test.ts'],
     });
 
     await cli.exec;
     expect(cli.exec.exitCode).toBe(0);
+    expect(cli.stdout).not.toContain('/scheduler.html');
   });
 });
diff --git a/packages/browser-ui/rsbuild.config.ts b/packages/browser-ui/rsbuild.config.ts
index f38898ea0..9238d9133 100644
--- a/packages/browser-ui/rsbuild.config.ts
+++ b/packages/browser-ui/rsbuild.config.ts
@@ -19,6 +19,7 @@ export default defineConfig({
   source: {
     entry: {
       index: './src/main.tsx',
+      scheduler: './src/scheduler.ts',
     },
   },
   output: {
diff --git a/packages/browser-ui/src/core/channel.ts b/packages/browser-ui/src/core/channel.ts
new file mode 100644
index 000000000..2d0f50392
--- /dev/null
+++ b/packages/browser-ui/src/core/channel.ts
@@ -0,0 +1,81 @@
+import type {
+  BrowserClientMessage,
+  HostRPC,
+  SnapshotRpcRequest,
+  SnapshotRpcResponse,
+} from '../types';
+
+const DISPATCH_MESSAGE_TYPE = '__rstest_dispatch__';
+const SNAPSHOT_RESPONSE_TYPE = '__rstest_snapshot_response__';
+
+type SnapshotRpcHandler = Pick<
+  HostRPC,
+  | 'resolveSnapshotPath'
+  | 'readSnapshotFile'
+  | 'saveSnapshotFile'
+  | 'removeSnapshotFile'
+>;
+
+const canPostMessage = (
+  sourceWindow: MessageEventSource | null,
+): sourceWindow is Window => {
+  return (
+    sourceWindow !== null &&
+    typeof (sourceWindow as Window).postMessage === 'function'
+  );
+};
+
+export const readDispatchMessage = (
+  event: MessageEvent,
+): BrowserClientMessage | null => {
+  if (event.data?.type !== DISPATCH_MESSAGE_TYPE) {
+    return null;
+  }
+  return event.data.payload as BrowserClientMessage;
+};
+
+export const forwardSnapshotRpcRequest = async (
+  rpc: SnapshotRpcHandler | null | undefined,
+  request: SnapshotRpcRequest,
+  sourceWindow: MessageEventSource | null,
+): Promise<void> => {
+  if (!rpc || !canPostMessage(sourceWindow)) {
+    return;
+  }
+
+  const sendResponse = (response: SnapshotRpcResponse) => {
+    sourceWindow.postMessage(
+      { type: SNAPSHOT_RESPONSE_TYPE, payload: response },
+      '*',
+    );
+  };
+
+  try {
+    let result: unknown;
+    switch (request.method) {
+      case 'resolveSnapshotPath':
+        result = await rpc.resolveSnapshotPath(request.args.testPath);
+        break;
+      case 'readSnapshotFile':
+        result = await rpc.readSnapshotFile(request.args.filepath);
+        break;
+      case 'saveSnapshotFile':
+        result = await rpc.saveSnapshotFile(
+          request.args.filepath,
+          request.args.content,
+        );
+        break;
+      case 'removeSnapshotFile':
+        result = await rpc.removeSnapshotFile(request.args.filepath);
+        break;
+      default:
+        result = undefined;
+    }
+    sendResponse({ id: request.id, result });
+  } catch (error) {
+    sendResponse({
+      id: request.id,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+};
diff --git a/packages/browser-ui/src/core/runtime.ts b/packages/browser-ui/src/core/runtime.ts
new file mode 100644
index 000000000..079318767
--- /dev/null
+++ b/packages/browser-ui/src/core/runtime.ts
@@ -0,0 +1,24 @@
+export const RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16_000, 30_000];
+
+export const createWebSocketUrl = (wsPort: number): string => {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${window.location.hostname}:${wsPort}`;
+};
+
+export const createRunnerUrl = (
+  testFile: string,
+  runnerBase?: string,
+  testNamePattern?: string,
+  cacheBust = false,
+): string => {
+  const base = runnerBase || window.location.origin;
+  const url = new URL('/runner.html', base);
+  url.searchParams.set('testFile', testFile);
+  if (testNamePattern) {
+    url.searchParams.set('testNamePattern', testNamePattern);
+  }
+  if (cacheBust) {
+    url.searchParams.set('t', Date.now().toString());
+  }
+  return url.toString();
+};
diff --git a/packages/browser-ui/src/hooks/useRpc.ts b/packages/browser-ui/src/hooks/useRpc.ts
index 648415321..ac15d8d46 100644
--- a/packages/browser-ui/src/hooks/useRpc.ts
+++ b/packages/browser-ui/src/hooks/useRpc.ts
@@ -1,58 +1,9 @@
 import { type BirpcReturn, createBirpc } from 'birpc';
 import { useEffect, useRef, useState } from 'react';
-import type {
-  BrowserClientFileResult,
-  BrowserClientTestResult,
-  TestFileInfo,
-} from '../types';
+import { createWebSocketUrl, RECONNECT_DELAYS } from '../core/runtime';
+import type { ContainerRPC, HostRPC, TestFileInfo } from '../types';
 import { logger } from '../utils/logger';
 
-// ============================================================================
-// RPC Types
-// ============================================================================
-
-/** Payload for test file start event */
-export type TestFileStartPayload = {
-  testPath: string;
-  projectName: string;
-};
-
-/** Payload for log event */
-export type LogPayload = {
-  level: 'log' | 'warn' | 'error' | 'info' | 'debug';
-  content: string;
-  testPath: string;
-  type: 'stdout' | 'stderr';
-  trace?: string;
-};
-
-/** Payload for fatal error event */
-export type FatalPayload = {
-  message: string;
-  stack?: string;
-};
-
-export type HostRPC = {
-  rerunTest: (testFile: string, testNamePattern?: string) => Promise<void>;
-  getTestFiles: () => Promise<TestFileInfo[]>;
-  // Test result callbacks from container
-  onTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
-  onTestCaseResult: (payload: BrowserClientTestResult) => Promise<void>;
-  onTestFileComplete: (payload: BrowserClientFileResult) => 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>;
-};
-
-export type ContainerRPC = {
-  onTestFileUpdate: (testFiles: TestFileInfo[]) => void;
-  reloadTestFile: (testFile: string, testNamePattern?: string) => void;
-};
-
 export type RpcState = {
   rpc: BirpcReturn<HostRPC, ContainerRPC> | null;
   loading: boolean;
@@ -63,8 +14,6 @@ export type RpcState = {
 // useRpc Hook - WebSocket connection with reconnect logic
 // ============================================================================
 
-const RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16000, 30000]; // Exponential backoff, max 30s
-
 export const useRpc = (
   setTestFiles: (files: TestFileInfo[]) => void,
   wsPort: number | undefined,
@@ -104,9 +53,7 @@ export const useRpc = (
     const connect = () => {
       if (!isMounted) return;
 
-      const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-      const wsUrl = `${protocol}//${window.location.hostname}:${wsPort}`;
-      ws = new WebSocket(wsUrl);
+      ws = new WebSocket(createWebSocketUrl(wsPort));
       activeWsRef.current = ws;
 
       const methods: ContainerRPC = {
diff --git a/packages/browser-ui/src/main.tsx b/packages/browser-ui/src/main.tsx
index 7c2cb0e6a..5357f362f 100644
--- a/packages/browser-ui/src/main.tsx
+++ b/packages/browser-ui/src/main.tsx
@@ -8,14 +8,16 @@ import { SidebarHeader } from './components/SidebarHeader';
 import { TestFilesHeader } from './components/TestFilesHeader';
 import { TestFilesTree } from './components/TestFilesTree';
 import { ViewportFrame } from './components/ViewportFrame';
+import { forwardSnapshotRpcRequest, readDispatchMessage } from './core/channel';
+import { createRunnerUrl } from './core/runtime';
 import { useRpc } from './hooks/useRpc';
 import type {
   BrowserClientFileResult,
-  BrowserClientMessage,
   BrowserClientTestResult,
   BrowserHostConfig,
+  FatalPayload,
+  LogPayload,
   SnapshotRpcRequest,
-  SnapshotRpcResponse,
   TestFileInfo,
 } from './types';
 import type {
@@ -38,20 +40,6 @@ const getDisplayName = (testFile: string): string => {
   return parts[parts.length - 1] || testFile;
 };
 
-const iframeUrlFor = (
-  testFile: string,
-  runnerBase?: string,
-  testNamePattern?: string,
-): string => {
-  const base = runnerBase || window.location.origin;
-  const url = new URL('/runner.html', base);
-  url.searchParams.set('testFile', testFile);
-  if (testNamePattern) {
-    url.searchParams.set('testNamePattern', testNamePattern);
-  }
-  return url.toString();
-};
-
 // ============================================================================
 // App Component
 // ============================================================================
@@ -193,7 +181,7 @@ const BrowserRunner: React.FC<{
           }
           return { ...prev, [testFile]: updatedCases };
         });
-        const newSrc = iframeUrlFor(
+        const newSrc = createRunnerUrl(
           testFile,
           options.runnerUrl,
           testNamePattern,
@@ -321,140 +309,84 @@ const BrowserRunner: React.FC<{
   // Handle messages from test runner iframes
   useEffect(() => {
     const listener = (event: MessageEvent) => {
-      if (event.data?.type === '__rstest_dispatch__') {
-        const message = event.data.payload as BrowserClientMessage | undefined;
-        if (message?.type === 'file-start') {
-          const payload = message.payload as {
-            testPath?: string;
-            projectName?: string;
-          };
-          const testPath = payload.testPath;
-          if (typeof testPath === 'string') {
-            setStatusMap((prev) => ({ ...prev, [testPath]: 'running' }));
-            setCaseMap((prev) => {
-              const prevFile = prev[testPath] ?? {};
-              const updatedCases: Record<string, CaseInfo> = {};
-              for (const [key, caseInfo] of Object.entries(prevFile)) {
-                updatedCases[key] = { ...caseInfo, status: 'running' };
-              }
-              return { ...prev, [testPath]: updatedCases };
-            });
-            // Forward to host via RPC
-            rpc?.onTestFileStart({
-              testPath,
-              projectName: payload.projectName ?? '',
-            });
-          }
-        } else if (message?.type === 'case-result') {
-          const payload = message.payload as BrowserClientTestResult;
-          if (payload?.testPath) {
-            upsertCase(payload.testPath, payload);
-            // Forward to host via RPC
-            rpc?.onTestCaseResult(payload);
-          }
-        } else if (message?.type === 'file-complete') {
-          const payload = message.payload as BrowserClientFileResult;
-          const testPath = payload.testPath;
-          if (typeof testPath === 'string') {
-            const passed =
-              payload.status === 'pass' || payload.status === 'skip';
-            setStatusMap((prev) => ({
-              ...prev,
-              [testPath]: passed ? 'pass' : 'fail',
-            }));
-            // Replace the caseMap for this file with only the cases that exist in the results
-            // This ensures deleted test cases are removed from the UI
-            setCaseMap((prev) => {
-              const newCases: Record<string, CaseInfo> = {};
-              for (const result of payload.results ?? []) {
-                if (result?.testId) {
-                  const parentNames = (result.parentNames ?? []).filter(
-                    Boolean,
-                  );
-                  const fullName =
-                    [...parentNames, result.name].join('  ') || result.name;
-                  newCases[result.testId] = {
-                    id: result.testId,
-                    name: result.name,
-                    parentNames,
-                    fullName,
-                    status: mapCaseStatus(result.status),
-                    filePath: result.testPath || testPath,
-                    location: result.location,
-                  };
-                }
-              }
-              return { ...prev, [testPath]: newCases };
-            });
-            // Forward to host via RPC
-            rpc?.onTestFileComplete(payload);
-          }
-        } else if (message?.type === 'fatal') {
-          if (active) {
-            setStatusMap((prev) => ({ ...prev, [active]: 'fail' }));
-          }
-          const payload = message.payload as {
-            message: string;
-            stack?: string;
-          };
-          // Forward to host via RPC
-          rpc?.onFatal(payload);
-        } else if (message?.type === 'log') {
-          const payload = message.payload as {
-            level: 'log' | 'warn' | 'error' | 'info' | 'debug';
-            content: string;
-            testPath: string;
-            type: 'stdout' | 'stderr';
-            trace?: string;
-          };
-          // Forward to host via RPC
-          rpc?.onLog(payload);
-        } else if (message?.type === 'snapshot-rpc-request') {
-          // Handle snapshot RPC requests from runner iframes
-          const request = message.payload as SnapshotRpcRequest;
-          const sourceWindow = event.source as Window | null;
-
-          if (!rpc || !sourceWindow) {
-            return;
-          }
+      const message = readDispatchMessage(event);
+      if (!message) {
+        return;
+      }
 
-          // Forward to host and send response back to iframe
-          const sendResponse = (response: SnapshotRpcResponse) => {
-            sourceWindow.postMessage(
-              { type: '__rstest_snapshot_response__', payload: response },
-              '*',
-            );
-          };
-
-          (async () => {
-            try {
-              let result: unknown;
-              switch (request.method) {
-                case 'resolveSnapshotPath':
-                  result = await rpc.resolveSnapshotPath(request.args.testPath);
-                  break;
-                case 'readSnapshotFile':
-                  result = await rpc.readSnapshotFile(request.args.filepath);
-                  break;
-                case 'saveSnapshotFile':
-                  result = await rpc.saveSnapshotFile(
-                    request.args.filepath,
-                    request.args.content,
-                  );
-                  break;
-                case 'removeSnapshotFile':
-                  result = await rpc.removeSnapshotFile(request.args.filepath);
-                  break;
+      if (message.type === 'file-start') {
+        const payload = message.payload as {
+          testPath?: string;
+          projectName?: string;
+        };
+        const testPath = payload.testPath;
+        if (typeof testPath === 'string') {
+          setStatusMap((prev) => ({ ...prev, [testPath]: 'running' }));
+          setCaseMap((prev) => {
+            const prevFile = prev[testPath] ?? {};
+            const updatedCases: Record<string, CaseInfo> = {};
+            for (const [key, caseInfo] of Object.entries(prevFile)) {
+              updatedCases[key] = { ...caseInfo, status: 'running' };
+            }
+            return { ...prev, [testPath]: updatedCases };
+          });
+          rpc?.onTestFileStart({
+            testPath,
+            projectName: payload.projectName ?? '',
+          });
+        }
+      } else if (message.type === 'case-result') {
+        const payload = message.payload as BrowserClientTestResult;
+        if (payload?.testPath) {
+          upsertCase(payload.testPath, payload);
+          rpc?.onTestCaseResult(payload);
+        }
+      } else if (message.type === 'file-complete') {
+        const payload = message.payload as BrowserClientFileResult;
+        const testPath = payload.testPath;
+        if (typeof testPath === 'string') {
+          const passed = payload.status === 'pass' || payload.status === 'skip';
+          setStatusMap((prev) => ({
+            ...prev,
+            [testPath]: passed ? 'pass' : 'fail',
+          }));
+          setCaseMap((prev) => {
+            const newCases: Record<string, CaseInfo> = {};
+            for (const result of payload.results ?? []) {
+              if (result?.testId) {
+                const parentNames = (result.parentNames ?? []).filter(Boolean);
+                const fullName =
+                  [...parentNames, result.name].join('  ') || result.name;
+                newCases[result.testId] = {
+                  id: result.testId,
+                  name: result.name,
+                  parentNames,
+                  fullName,
+                  status: mapCaseStatus(result.status),
+                  filePath: result.testPath || testPath,
+                  location: result.location,
+                };
               }
-              sendResponse({ id: request.id, result });
-            } catch (error) {
-              sendResponse({
-                id: request.id,
-                error: error instanceof Error ? error.message : String(error),
-              });
             }
-          })();
+            return { ...prev, [testPath]: newCases };
+          });
+          rpc?.onTestFileComplete(payload);
         }
+      } else if (message.type === 'fatal') {
+        if (active) {
+          setStatusMap((prev) => ({ ...prev, [active]: 'fail' }));
+        }
+        const payload = message.payload as FatalPayload;
+        rpc?.onFatal(payload);
+      } else if (message.type === 'log') {
+        const payload = message.payload as LogPayload;
+        rpc?.onLog(payload);
+      } else if (message.type === 'snapshot-rpc-request') {
+        void forwardSnapshotRpcRequest(
+          rpc,
+          message.payload as SnapshotRpcRequest,
+          event.source,
+        );
       }
     };
     window.addEventListener('message', listener);
@@ -750,7 +682,7 @@ const BrowserRunner: React.FC<{
                         <iframe
                           data-test-file={fileInfo.testPath}
                           title={`Test runner for ${getDisplayName(fileInfo.testPath)}`}
-                          src={iframeUrlFor(
+                          src={createRunnerUrl(
                             fileInfo.testPath,
                             options.runnerUrl,
                           )}
diff --git a/packages/browser-ui/src/scheduler.ts b/packages/browser-ui/src/scheduler.ts
new file mode 100644
index 000000000..d3110d3b3
--- /dev/null
+++ b/packages/browser-ui/src/scheduler.ts
@@ -0,0 +1,288 @@
+import { type BirpcReturn, createBirpc } from 'birpc';
+import { forwardSnapshotRpcRequest, readDispatchMessage } from './core/channel';
+import {
+  createRunnerUrl,
+  createWebSocketUrl,
+  RECONNECT_DELAYS,
+} from './core/runtime';
+import type {
+  BrowserClientFileResult,
+  BrowserClientMessage,
+  BrowserClientTestResult,
+  BrowserHostConfig,
+  ContainerRPC,
+  FatalPayload,
+  HostRPC,
+  LogPayload,
+  SnapshotRpcRequest,
+  TestFileInfo,
+  TestFileStartPayload,
+} from './types';
+import { getPresetInfo, isDevicePreset } from './utils/viewportPresets';
+
+declare global {
+  interface Window {
+    __RSTEST_BROWSER_OPTIONS__?: BrowserHostConfig;
+  }
+}
+
+type SchedulerRpc = BirpcReturn<HostRPC, ContainerRPC>;
+
+const options = window.__RSTEST_BROWSER_OPTIONS__;
+const debug = options?.debug === true;
+const rpcTimeout = options?.rpcTimeout ?? 30_000;
+
+let rpc: SchedulerRpc | null = null;
+let reconnectAttempt = 0;
+let reconnectTimeoutId: ReturnType<typeof setTimeout> | null = null;
+const iframeMap = new Map<string, HTMLIFrameElement>();
+const fileProjectMap = new Map<string, string>();
+
+const debugLog = (...args: unknown[]) => {
+  if (debug) {
+    console.log('[Scheduler]', ...args);
+  }
+};
+
+const resolveViewport = (
+  testFile: string,
+): { width: number; height: number } | null => {
+  const projectName = fileProjectMap.get(testFile);
+  if (!projectName) {
+    return null;
+  }
+
+  const project = options?.projects.find((item) => item.name === projectName);
+  const viewport = project?.viewport;
+  if (!viewport) {
+    return null;
+  }
+
+  if (typeof viewport === 'string' && isDevicePreset(viewport)) {
+    const preset = getPresetInfo(viewport);
+    return { width: preset.width, height: preset.height };
+  }
+
+  if (
+    typeof viewport === 'object' &&
+    viewport !== null &&
+    typeof viewport.width === 'number' &&
+    typeof viewport.height === 'number'
+  ) {
+    return { width: viewport.width, height: viewport.height };
+  }
+
+  return null;
+};
+
+const postConfig = (frame: HTMLIFrameElement, testFile: string): void => {
+  const projectName = fileProjectMap.get(testFile) || '';
+  frame.contentWindow?.postMessage(
+    {
+      type: 'RSTEST_CONFIG',
+      payload: {
+        ...options,
+        testFile,
+        projectName,
+      },
+    },
+    '*',
+  );
+};
+
+const mountRunner = (testFile: string, testNamePattern?: string): void => {
+  let iframe = iframeMap.get(testFile);
+  if (!iframe) {
+    iframe = document.createElement('iframe');
+    iframe.style.position = 'fixed';
+    iframe.style.left = '0';
+    iframe.style.top = '0';
+    iframe.style.opacity = '0';
+    iframe.style.pointerEvents = 'none';
+    iframe.style.border = '0';
+    iframe.title = `Scheduler runner for ${testFile}`;
+    iframe.dataset.testFile = testFile;
+    iframe.addEventListener('load', () => {
+      postConfig(iframe!, testFile);
+    });
+    document.body.appendChild(iframe);
+    iframeMap.set(testFile, iframe);
+  }
+
+  const viewport = resolveViewport(testFile);
+  if (viewport) {
+    iframe.style.width = `${viewport.width}px`;
+    iframe.style.height = `${viewport.height}px`;
+  } else {
+    iframe.style.width = '100vw';
+    iframe.style.height = '100vh';
+  }
+
+  iframe.src = createRunnerUrl(
+    testFile,
+    options?.runnerUrl,
+    testNamePattern,
+    true,
+  );
+};
+
+const unmountRemovedFiles = (nextFiles: TestFileInfo[]): void => {
+  const nextSet = new Set(nextFiles.map((f) => f.testPath));
+  for (const [testFile, frame] of iframeMap.entries()) {
+    if (!nextSet.has(testFile)) {
+      frame.remove();
+      iframeMap.delete(testFile);
+      fileProjectMap.delete(testFile);
+    }
+  }
+};
+
+const syncFiles = (files: TestFileInfo[]): void => {
+  const previous = new Set(fileProjectMap.keys());
+  unmountRemovedFiles(files);
+  for (const file of files) {
+    fileProjectMap.set(file.testPath, file.projectName);
+  }
+  const added = files.filter((file) => !previous.has(file.testPath));
+  for (const file of added) {
+    mountRunner(file.testPath);
+  }
+};
+
+const forwardClientMessage = async (
+  message: BrowserClientMessage,
+): Promise<void> => {
+  if (!rpc) {
+    return;
+  }
+
+  try {
+    switch (message.type) {
+      case 'file-start':
+        await rpc.onTestFileStart(message.payload as TestFileStartPayload);
+        break;
+      case 'case-result':
+        await rpc.onTestCaseResult(message.payload as BrowserClientTestResult);
+        break;
+      case 'file-complete':
+        await rpc.onTestFileComplete(
+          message.payload as BrowserClientFileResult,
+        );
+        break;
+      case 'log':
+        await rpc.onLog(message.payload as LogPayload);
+        break;
+      case 'fatal':
+        await rpc.onFatal(message.payload as FatalPayload);
+        break;
+      default:
+        break;
+    }
+  } catch (error) {
+    debugLog('failed to forward client message', error);
+  }
+};
+
+const scheduleReconnect = () => {
+  const delay =
+    RECONNECT_DELAYS[Math.min(reconnectAttempt, RECONNECT_DELAYS.length - 1)];
+  reconnectAttempt++;
+  debugLog(`reconnecting in ${delay}ms`);
+  reconnectTimeoutId = setTimeout(() => {
+    void connect().catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      debugLog('reconnect attempt failed', message);
+      scheduleReconnect();
+    });
+  }, delay);
+};
+
+const connect = async (): Promise<void> => {
+  if (!options?.wsPort) {
+    throw new Error('Scheduler requires wsPort in browser options.');
+  }
+
+  if (reconnectTimeoutId) {
+    clearTimeout(reconnectTimeoutId);
+    reconnectTimeoutId = null;
+  }
+
+  const ws = new WebSocket(createWebSocketUrl(options.wsPort));
+
+  await new Promise<void>((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(new Error(`Scheduler websocket timeout after ${rpcTimeout}ms`));
+    }, rpcTimeout);
+
+    ws.addEventListener('open', () => {
+      clearTimeout(timeoutId);
+      resolve();
+    });
+    ws.addEventListener('error', () => {
+      clearTimeout(timeoutId);
+      reject(new Error('Scheduler websocket failed to connect.'));
+    });
+  });
+
+  reconnectAttempt = 0;
+
+  const methods: ContainerRPC = {
+    onTestFileUpdate(testFiles) {
+      debugLog('onTestFileUpdate', testFiles.length);
+      syncFiles(testFiles);
+    },
+    reloadTestFile(testFile, testNamePattern) {
+      debugLog('reloadTestFile', testFile, testNamePattern);
+      mountRunner(testFile, testNamePattern);
+    },
+  };
+
+  rpc = createBirpc<HostRPC, ContainerRPC>(methods, {
+    timeout: rpcTimeout,
+    post(data) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(data));
+      }
+    },
+    on(fn) {
+      ws.addEventListener('message', (event) => {
+        try {
+          fn(JSON.parse(String(event.data)));
+        } catch {
+          // ignore invalid payloads
+        }
+      });
+    },
+  });
+
+  ws.addEventListener('close', () => {
+    debugLog('websocket closed');
+    rpc = null;
+    scheduleReconnect();
+  });
+
+  const files = await rpc.getTestFiles();
+  syncFiles(files);
+};
+
+window.addEventListener('message', (event: MessageEvent) => {
+  const message = readDispatchMessage(event);
+  if (!message) {
+    return;
+  }
+  if (message.type === 'snapshot-rpc-request') {
+    void forwardSnapshotRpcRequest(
+      rpc,
+      message.payload as SnapshotRpcRequest,
+      event.source,
+    );
+    return;
+  }
+  void forwardClientMessage(message);
+});
+
+void connect().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error('[Scheduler] Failed to initialize:', message);
+  scheduleReconnect();
+});
diff --git a/packages/browser-ui/src/types.ts b/packages/browser-ui/src/types.ts
index c5a252781..abbcc7fe8 100644
--- a/packages/browser-ui/src/types.ts
+++ b/packages/browser-ui/src/types.ts
@@ -41,6 +41,8 @@ export type BrowserHostConfig = {
   wsPort?: number;
   /** Debug mode. When true, enables verbose logging in browser */
   debug?: boolean;
+  /** Timeout for RPC operations in milliseconds */
+  rpcTimeout?: number;
 };
 
 export type BrowserClientTestResult = {
@@ -60,11 +62,29 @@ export type BrowserClientFileResult = BrowserClientTestResult & {
   results: BrowserClientTestResult[];
 };
 
+export type TestFileStartPayload = {
+  testPath: string;
+  projectName: string;
+};
+
+export type LogPayload = {
+  level: 'log' | 'warn' | 'error' | 'info' | 'debug';
+  content: string;
+  testPath: string;
+  type: 'stdout' | 'stderr';
+  trace?: string;
+};
+
+export type FatalPayload = {
+  message: string;
+  stack?: string;
+};
+
 export type BrowserClientMessage =
   | { type: 'ready' }
   | {
       type: 'file-start';
-      payload: { testPath: string; projectName: string };
+      payload: TestFileStartPayload;
     }
   | {
       type: 'case-result';
@@ -76,7 +96,11 @@ export type BrowserClientMessage =
     }
   | {
       type: 'fatal';
-      payload: { message: string; stack?: string };
+      payload: FatalPayload;
+    }
+  | {
+      type: 'log';
+      payload: LogPayload;
     }
   | {
       type: 'snapshot-rpc-request';
@@ -84,6 +108,25 @@ export type BrowserClientMessage =
     }
   | { type: string; payload?: unknown };
 
+export type HostRPC = {
+  rerunTest: (testFile: string, testNamePattern?: string) => Promise<void>;
+  getTestFiles: () => Promise<TestFileInfo[]>;
+  onTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
+  onTestCaseResult: (payload: BrowserClientTestResult) => Promise<void>;
+  onTestFileComplete: (payload: BrowserClientFileResult) => Promise<void>;
+  onLog: (payload: LogPayload) => Promise<void>;
+  onFatal: (payload: FatalPayload) => Promise<void>;
+  resolveSnapshotPath: (testPath: string) => Promise<string>;
+  readSnapshotFile: (filepath: string) => Promise<string | null>;
+  saveSnapshotFile: (filepath: string, content: string) => Promise<void>;
+  removeSnapshotFile: (filepath: string) => Promise<void>;
+};
+
+export type ContainerRPC = {
+  onTestFileUpdate: (testFiles: TestFileInfo[]) => void;
+  reloadTestFile: (testFile: string, testNamePattern?: string) => void;
+};
+
 /**
  * Snapshot RPC request from runner iframe.
  * The container will forward these to the host via WebSocket RPC.
diff --git a/packages/browser/src/hostController.ts b/packages/browser/src/hostController.ts
index 4a1db8eca..aee727e07 100644
--- a/packages/browser/src/hostController.ts
+++ b/packages/browser/src/hostController.ts
@@ -44,6 +44,19 @@ type RsbuildDevServer = rsbuild.RsbuildDevServer;
 type RsbuildInstance = rsbuild.RsbuildInstance;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const OPTIONS_PLACEHOLDER = '__RSTEST_OPTIONS_PLACEHOLDER__';
+
+/**
+ * Serialize JSON for inline <script> injection.
+ * Escapes '<' to prevent accidental </script> break-out.
+ * Escapes U+2028/U+2029 to keep script parsing safe.
+ */
+const serializeForInlineScript = (value: unknown): string => {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+};
 
 // ============================================================================
 // Type Definitions
@@ -716,6 +729,21 @@ 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
@@ -800,22 +828,30 @@ const createBrowserRuntime = async ({
     [manifestPath]: manifestSource,
   });
 
-  const optionsPlaceholder = '__RSTEST_OPTIONS_PLACEHOLDER__';
   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';
 
   const setContainerOptions = (options: BrowserHostConfig): void => {
-    serializedOptions = JSON.stringify(options).replace(/</g, '\\u003c');
+    serializedOptions = serializeForInlineScript(options);
     if (containerHtmlTemplate) {
       injectedContainerHtml = containerHtmlTemplate.replace(
-        optionsPlaceholder,
+        OPTIONS_PLACEHOLDER,
         serializedOptions,
       );
     }
+    injectedSchedulerHtml = (
+      schedulerHtmlTemplate || fallbackSchedulerHtmlTemplate
+    ).replace(OPTIONS_PLACEHOLDER, serializedOptions);
   };
 
   // Get user Rsbuild config from the first browser project
@@ -1020,7 +1056,7 @@ const createBrowserRuntime = async ({
       }
 
       let html = await response.text();
-      html = html.replace(optionsPlaceholder, serializedOptions);
+      html = html.replace(OPTIONS_PLACEHOLDER, serializedOptions);
 
       res.statusCode = response.status;
       response.headers.forEach((value, key) => {
@@ -1097,14 +1133,26 @@ const createBrowserRuntime = async ({
       }
       return;
     }
-    if (url.pathname === '/') {
+    if (url.pathname === '/' || url.pathname === '/scheduler.html') {
       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(optionsPlaceholder, 'null');
+        containerHtmlTemplate?.replace(OPTIONS_PLACEHOLDER, 'null');
 
       if (html) {
         res.setHeader('Content-Type', 'text/html');
@@ -1232,6 +1280,10 @@ export const runBrowserController = async (
 ): Promise<BrowserTestRunResult | void> => {
   const { skipOnTestRunEnd = false } = options ?? {};
   const buildStart = Date.now();
+  const browserProjects = getBrowserProjects(context);
+  const useSchedulerPage = browserProjects.every(
+    (project) => project.normalizedConfig.browser.headless,
+  );
 
   /**
    * Build an error BrowserTestRunResult and call onTestRunEnd if needed.
@@ -1405,21 +1457,19 @@ export const runBrowserController = async (
 
   // Only include browser mode projects in runtime configs
   // Normalize projectRoot to posix format for cross-platform compatibility
-  const browserProjectsForRuntime = getBrowserProjects(context);
-  const projectRuntimeConfigs: BrowserProjectRuntime[] =
-    browserProjectsForRuntime.map((project: ProjectContext) => ({
+  const projectRuntimeConfigs: BrowserProjectRuntime[] = browserProjects.map(
+    (project: ProjectContext) => ({
       name: project.name,
       environmentName: project.environmentName,
       projectRoot: normalize(project.rootPath),
       runtimeConfig: serializableConfig(getRuntimeConfigFromProject(project)),
       viewport: project.normalizedConfig.browser.viewport,
-    }));
+    }),
+  );
 
   // Get max testTimeout from all browser projects for RPC timeout
   const maxTestTimeoutForRpc = Math.max(
-    ...browserProjectsForRuntime.map(
-      (p) => p.normalizedConfig.testTimeout ?? 5000,
-    ),
+    ...browserProjects.map((p) => p.normalizedConfig.testTimeout ?? 5000),
   );
 
   const hostOptions: BrowserHostConfig = {
@@ -1483,7 +1533,11 @@ export const runBrowserController = async (
     // Forward browser console to terminal
     containerPage.on('console', (msg: ConsoleMessage) => {
       const text = msg.text();
-      if (text.includes('[Container]') || text.includes('[Runner]')) {
+      if (
+        text.startsWith('[Container]') ||
+        text.startsWith('[Runner]') ||
+        text.startsWith('[Scheduler]')
+      ) {
         logger.log(color.gray(`[Browser Console] ${text}`));
       }
     });
@@ -1624,21 +1678,28 @@ export const runBrowserController = async (
 
   // Only navigate on first creation
   if (isNewPage) {
-    await containerPage.goto(`http://localhost:${port}/`, {
+    const pagePath = useSchedulerPage ? '/scheduler.html' : '/';
+    if (useSchedulerPage) {
+      const serializedOptions = serializeForInlineScript(hostOptions);
+      await containerPage.addInitScript(
+        `window.__RSTEST_BROWSER_OPTIONS__ = ${serializedOptions};`,
+      );
+    }
+    await containerPage.goto(`http://localhost:${port}${pagePath}`, {
       waitUntil: 'load',
     });
 
     logger.log(
-      color.cyan(`\nBrowser mode opened at http://localhost:${port}/\n`),
+      color.cyan(
+        `\nBrowser mode opened at http://localhost:${port}${pagePath}\n`,
+      ),
     );
   }
 
   // Wait for all tests to complete
   // Calculate total timeout based on config: max testTimeout * file count + buffer
   const maxTestTimeout = Math.max(
-    ...browserProjectsForRuntime.map(
-      (p) => p.normalizedConfig.testTimeout ?? 5000,
-    ),
+    ...browserProjects.map((p) => p.normalizedConfig.testTimeout ?? 5000),
   );
   const totalTimeoutMs = maxTestTimeout * allTestFiles.length + 30_000;
 
@@ -1710,6 +1771,16 @@ export const runBrowserController = async (
   }
 
   if (!isWatchMode) {
+    try {
+      await containerPage.close();
+    } catch {
+      // ignore
+    }
+    try {
+      await containerContext.close();
+    } catch {
+      // ignore
+    }
     await destroyBrowserRuntime(runtime);
   }
 
@@ -1932,10 +2003,7 @@ export const listBrowserTests = async (
   );
 
   // Inject host options before navigation so the runner can access them
-  const serializedOptions = JSON.stringify(hostOptions).replace(
-    /</g,
-    '\\u003c',
-  );
+  const serializedOptions = serializeForInlineScript(hostOptions);
   await page.addInitScript(
     `window.__RSTEST_BROWSER_OPTIONS__ = ${serializedOptions};`,
   );