@rstest/browser 0.10.2 → 0.10.4

package/src/concurrency.ts

@@ -1,5 +1,9 @@
-import os from 'node:os';
-import type { Rstest } from '@rstest/core/browser';
+import { getNumCpus, parseWorkers } from '@rstest/core/internal/browser';
+import type { Rstest } from '@rstest/core/internal/browser';
+
+// Re-export the shared worker primitives so existing consumers (and unit tests
+// importing from `../src/concurrency`) keep a stable import surface.
+export { getNumCpus, parseWorkers };
 
 // Shared headless concurrency policy.
 // Keep this in one place so executors reuse the same worker semantics.
@@ -13,24 +17,6 @@ type HeadlessConcurrencyContext = Pick<Rstest, 'command'> & {
   };
 };
 
-const getNumCpus = (): number => {
-  return os.availableParallelism?.() ?? os.cpus().length;
-};
-
-export const parseWorkers = (
-  maxWorkers: string | number,
-  numCpus = getNumCpus(),
-): number => {
-  const parsed = Number.parseInt(maxWorkers.toString(), 10);
-
-  if (typeof maxWorkers === 'string' && maxWorkers.trim().endsWith('%')) {
-    const workers = Math.floor((parsed / 100) * numCpus);
-    return Math.max(workers, 1);
-  }
-
-  return parsed > 0 ? parsed : 1;
-};
-
 export const resolveDefaultHeadlessWorkers = (
   command: HeadlessConcurrencyContext['command'],
   numCpus = getNumCpus(),

package/src/configValidation.ts

@@ -1,4 +1,4 @@
-import type { Rstest } from '@rstest/core/browser';
+import type { RstestContext } from '@rstest/core/internal/browser';
 import { resolveBrowserViewportPreset } from './viewportPresets';
 
 const SUPPORTED_PROVIDERS = ['playwright'] as const;
@@ -42,7 +42,7 @@ const validateViewport = (viewport: unknown): void => {
   );
 };
 
-export const validateBrowserConfig = (context: Rstest): void => {
+export const validateBrowserConfig = (context: RstestContext): void => {
   for (const project of context.projects) {
     const { browser, output } = project.normalizedConfig;
     if (!browser.enabled) {

package/src/dispatchCapabilities.ts

@@ -1,9 +1,16 @@
-import type { Reporter } from '@rstest/core/browser';
+import type { Reporter } from '@rstest/core/internal/browser';
 import { HostDispatchRouter } from './dispatchRouter';
+import {
+  DISPATCH_NAMESPACE_RUNNER,
+  DISPATCH_NAMESPACE_SNAPSHOT,
+} from './protocol';
 import type {
   BrowserClientMessage,
   BrowserDispatchHandler,
   BrowserDispatchRequest,
+  RunnerDispatchMethod,
+  SnapshotRpcMethod,
+  SnapshotRpcMethodArgs,
   SnapshotRpcRequest,
 } from './protocol';
 
@@ -52,37 +59,50 @@ type CreateHostDispatchRouterOptions = {
   onDuplicateNamespace?: (namespace: string) => void;
 };
 
+/**
+ * Builds a typed {@link SnapshotRpcRequest} from the untrusted wire envelope,
+ * one builder per method. Keyed by {@link SnapshotRpcMethod}, so adding or
+ * renaming a method in the union forces a matching entry here — a stale name
+ * becomes a compile error instead of silently falling through to `null`. The
+ * `args` casts are the unavoidable trust boundary for inbound wire data.
+ */
+const snapshotRequestBuilders: {
+  [M in SnapshotRpcMethod]: (
+    id: string,
+    args: BrowserDispatchRequest['args'],
+  ) => Extract<SnapshotRpcRequest, { method: M }>;
+} = {
+  resolveSnapshotPath: (id, args) => ({
+    id,
+    method: 'resolveSnapshotPath',
+    args: args as SnapshotRpcMethodArgs['resolveSnapshotPath'],
+  }),
+  readSnapshotFile: (id, args) => ({
+    id,
+    method: 'readSnapshotFile',
+    args: args as SnapshotRpcMethodArgs['readSnapshotFile'],
+  }),
+  saveSnapshotFile: (id, args) => ({
+    id,
+    method: 'saveSnapshotFile',
+    args: args as SnapshotRpcMethodArgs['saveSnapshotFile'],
+  }),
+  removeSnapshotFile: (id, args) => ({
+    id,
+    method: 'removeSnapshotFile',
+    args: args as SnapshotRpcMethodArgs['removeSnapshotFile'],
+  }),
+};
+
 const toSnapshotRpcRequest = (
   request: BrowserDispatchRequest,
 ): SnapshotRpcRequest | null => {
-  switch (request.method) {
-    case 'resolveSnapshotPath':
-      return {
-        id: request.requestId,
-        method: 'resolveSnapshotPath',
-        args: request.args as { testPath: string },
-      };
-    case 'readSnapshotFile':
-      return {
-        id: request.requestId,
-        method: 'readSnapshotFile',
-        args: request.args as { filepath: string },
-      };
-    case 'saveSnapshotFile':
-      return {
-        id: request.requestId,
-        method: 'saveSnapshotFile',
-        args: request.args as { filepath: string; content: string },
-      };
-    case 'removeSnapshotFile':
-      return {
-        id: request.requestId,
-        method: 'removeSnapshotFile',
-        args: request.args as { filepath: string },
-      };
-    default:
-      return null;
-  }
+  const builder = snapshotRequestBuilders[
+    request.method as SnapshotRpcMethod
+  ] as
+    | ((id: string, args: BrowserDispatchRequest['args']) => SnapshotRpcRequest)
+    | undefined;
+  return builder ? builder(request.requestId, request.args) : null;
 };
 
 export const createHostDispatchRouter = ({
@@ -94,61 +114,60 @@ export const createHostDispatchRouter = ({
 }: CreateHostDispatchRouterOptions): HostDispatchRouter => {
   const router = new HostDispatchRouter(routerOptions);
 
-  router.register('runner', async (request: BrowserDispatchRequest) => {
-    switch (request.method) {
-      case 'file-start':
-        await runnerCallbacks.onTestFileStart(
-          request.args as RunnerPayload<'file-start'>,
-        );
-        break;
-      case 'file-ready':
-        await runnerCallbacks.onTestFileReady(
-          request.args as RunnerDispatchFileReadyPayload,
-        );
-        break;
-      case 'suite-start':
-        await runnerCallbacks.onTestSuiteStart(
-          request.args as RunnerDispatchSuiteStartPayload,
-        );
-        break;
-      case 'suite-result':
-        await runnerCallbacks.onTestSuiteResult(
-          request.args as RunnerDispatchSuiteResultPayload,
-        );
-        break;
-      case 'case-start':
-        await runnerCallbacks.onTestCaseStart(
-          request.args as RunnerDispatchCaseStartPayload,
-        );
-        break;
-      case 'case-result':
-        await runnerCallbacks.onTestCaseResult(
-          request.args as RunnerPayload<'case-result'>,
-        );
-        break;
-      case 'file-complete':
-        await runnerCallbacks.onTestFileComplete(
-          request.args as RunnerPayload<'file-complete'>,
-        );
-        break;
-      case 'log':
-        await runnerCallbacks.onLog(request.args as RunnerPayload<'log'>);
-        break;
-      case 'fatal':
-        await runnerCallbacks.onFatal(request.args as RunnerPayload<'fatal'>);
-        break;
-      default:
-        break;
-    }
-  });
+  // Keyed by RunnerDispatchMethod so adding a runner method to that union forces
+  // a handler entry here (a missing key is a compile error) — the previous
+  // `switch` with `default: break` silently dropped unhandled methods. The
+  // `args` casts are checked against each callback's parameter type, so a wrong
+  // payload type also fails to compile.
+  const runnerMethodHandlers: {
+    [M in RunnerDispatchMethod]: (
+      args: BrowserDispatchRequest['args'],
+    ) => Promise<void>;
+  } = {
+    'file-start': (args) =>
+      runnerCallbacks.onTestFileStart(args as RunnerPayload<'file-start'>),
+    'file-ready': (args) =>
+      runnerCallbacks.onTestFileReady(args as RunnerDispatchFileReadyPayload),
+    'suite-start': (args) =>
+      runnerCallbacks.onTestSuiteStart(args as RunnerDispatchSuiteStartPayload),
+    'suite-result': (args) =>
+      runnerCallbacks.onTestSuiteResult(
+        args as RunnerDispatchSuiteResultPayload,
+      ),
+    'case-start': (args) =>
+      runnerCallbacks.onTestCaseStart(args as RunnerDispatchCaseStartPayload),
+    'case-result': (args) =>
+      runnerCallbacks.onTestCaseResult(args as RunnerPayload<'case-result'>),
+    'file-complete': (args) =>
+      runnerCallbacks.onTestFileComplete(
+        args as RunnerPayload<'file-complete'>,
+      ),
+    log: (args) => runnerCallbacks.onLog(args as RunnerPayload<'log'>),
+    fatal: (args) => runnerCallbacks.onFatal(args as RunnerPayload<'fatal'>),
+  };
 
-  router.register('snapshot', async (request: BrowserDispatchRequest) => {
-    const snapshotRequest = toSnapshotRpcRequest(request);
-    if (!snapshotRequest) {
-      return undefined;
-    }
-    return runSnapshotRpc(snapshotRequest);
-  });
+  router.register(
+    DISPATCH_NAMESPACE_RUNNER,
+    async (request: BrowserDispatchRequest) => {
+      // `request.method` is untrusted wire data, so the lookup may miss. Unknown
+      // methods are ignored for forward-compatibility with newer runners,
+      // matching the previous `default: break`.
+      await runnerMethodHandlers[request.method as RunnerDispatchMethod]?.(
+        request.args,
+      );
+    },
+  );
+
+  router.register(
+    DISPATCH_NAMESPACE_SNAPSHOT,
+    async (request: BrowserDispatchRequest) => {
+      const snapshotRequest = toSnapshotRpcRequest(request);
+      if (!snapshotRequest) {
+        return undefined;
+      }
+      return runSnapshotRpc(snapshotRequest);
+    },
+  );
 
   for (const [namespace, handler] of extensionHandlers ?? []) {
     if (router.has(namespace)) {

package/src/env.d.ts

@@ -1,3 +1,4 @@
+import { DISPATCH_MESSAGE_TYPE, DISPATCH_RPC_BRIDGE_NAME } from './protocol';
 import type {
   BrowserClientMessage,
   BrowserDispatchRequest,
@@ -38,8 +39,11 @@ declare global {
 
   interface Window {
     __RSTEST_BROWSER_OPTIONS__?: BrowserHostConfig;
-    __rstest_dispatch__?: (message: BrowserClientMessage) => void;
-    __rstest_dispatch_rpc__?: (
+    // Keyed by the sentinel constants so the declared global name and the
+    // constant are the same source — renaming a constant moves this key with it,
+    // and every `window[CONST]` access site stays in lockstep automatically.
+    [DISPATCH_MESSAGE_TYPE]?: (message: BrowserClientMessage) => void;
+    [DISPATCH_RPC_BRIDGE_NAME]?: (
       request: BrowserDispatchRequest,
     ) => Promise<unknown>;
     __rstest_container_dispatch__?: (data: unknown) => void;

package/src/hostController.ts

@@ -11,6 +11,7 @@ import {
   type CoverageMapData,
   color,
   createCoverageProvider,
+  DEFAULT_TEST_TIMEOUT,
   type FormattedError,
   getNoTestFilesMessage,
   getSetupFiles,
@@ -22,16 +23,17 @@ import {
   PhaseTracker,
   type ProjectContext,
   type Reporter,
-  type Rstest,
+  type RstestContext,
   type RuntimeConfig,
   resolveProjectBuildCache,
+  RSTEST_ENV_SYMBOL_KEY,
   rsbuild,
   serializableConfig,
   type Test,
   type TestFileResult,
   type TestResult,
   type UserConsoleLog,
-} from '@rstest/core/browser';
+} from '@rstest/core/internal/browser';
 import { type BirpcReturn, createBirpc } from 'birpc';
 import openEditor from 'open-editor';
 import { basename, dirname, join, normalize, relative, resolve } from 'pathe';
@@ -52,6 +54,7 @@ import type {
   BrowserDispatchRequest,
   BrowserDispatchResponse,
   BrowserHostConfig,
+  BrowserLogPayload,
   BrowserProjectRuntime,
   BrowserRpcRequest,
   BrowserViewport,
@@ -60,6 +63,7 @@ import type {
 } from './protocol';
 import {
   DISPATCH_MESSAGE_TYPE,
+  DISPATCH_NAMESPACE_BROWSER,
   DISPATCH_NAMESPACE_RUNNER,
   validateBrowserRpcRequest,
 } from './protocol';
@@ -97,6 +101,15 @@ type RsbuildInstance = rsbuild.RsbuildInstance;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const OPTIONS_PLACEHOLDER = '__RSTEST_OPTIONS_PLACEHOLDER__';
 
+/**
+ * Extra time added on top of a file's `testTimeout` before the host gives up
+ * waiting for that file's RPC to settle. Covers fixed per-file overhead (page
+ * navigation, runner boot) that is not part of the user's test budget. The
+ * headless and headed scheduling paths both apply this same buffer, so it lives
+ * here as one constant to keep their per-file timeout semantics identical.
+ */
+const PER_FILE_TIMEOUT_BUFFER_MS = 30_000;
+
 /**
  * Monotonic counter for synthetic per-file Perfetto `pid` values in `--trace`
  * mode. Browser host runs every test file inside the same Node process, so
@@ -165,18 +178,8 @@ type TestFileStartPayload = {
   projectName: string;
 };
 
-/** Payload for log event */
-type LogPayload = {
-  level: 'log' | 'warn' | 'error' | 'info' | 'debug';
-  content: string;
-  taskId?: string;
-  taskName?: string;
-  taskParentNames?: string[];
-  taskType?: 'file' | 'suite' | 'case';
-  testPath: string;
-  type: 'stdout' | 'stderr';
-  trace?: string;
-};
+/** Payload for log event — single-sourced from the wire protocol. */
+type LogPayload = BrowserLogPayload;
 
 /** Payload for fatal error event */
 type FatalPayload = {
@@ -830,11 +833,16 @@ const getRuntimeConfigFromProject = (
   } = project.normalizedConfig;
 
   return {
-    // Propagate NODE_ENV from the host so `import.meta.env.NODE_ENV` resolves
-    // to `'test'` in browser tests (matches Node mode). User-supplied `env`
-    // wins so explicit overrides still take effect.
+    // Propagate NODE_ENV and the RSTEST flag from the host so
+    // `process.env.NODE_ENV` / `process.env.RSTEST` (rewritten to the
+    // `RSTEST_ENV_SYMBOL_KEY` symbol store) resolve in browser tests the same
+    // way they do in Node mode, where `prepare.ts` sets them on the real
+    // `process.env`.
+    // User-supplied `env` wins so explicit overrides still take effect.
+    // See https://github.com/web-infra-dev/rstest/issues/1351
     env: {
       NODE_ENV: process.env.NODE_ENV,
+      RSTEST: 'true',
       ...env,
     },
     testNamePattern,
@@ -864,7 +872,7 @@ const getRuntimeConfigFromProject = (
   };
 };
 
-const getBrowserProjects = (context: Rstest): ProjectContext[] => {
+const getBrowserProjects = (context: RstestContext): ProjectContext[] => {
   return context.projects.filter(
     (project) => project.normalizedConfig.browser.enabled,
   );
@@ -936,7 +944,7 @@ const resolveProviderForTestPath = ({
 };
 
 const collectProjectEntries = async (
-  context: Rstest,
+  context: RstestContext,
 ): Promise<BrowserProjectEntries[]> => {
   // Only collect entries for browser mode projects
   const browserProjects = getBrowserProjects(context);
@@ -1211,7 +1219,7 @@ const createBrowserRuntime = async ({
   containerDevServer,
   forceHeadless,
 }: {
-  context: Rstest;
+  context: RstestContext;
   manifestPath: string;
   manifestSource: string;
   tempDir: string;
@@ -1257,7 +1265,7 @@ const createBrowserRuntime = async ({
 
   // Rstest internal aliases that must not be overridden by user config
   const browserRuntimePath = fileURLToPath(
-    import.meta.resolve('@rstest/core/browser-runtime'),
+    import.meta.resolve('@rstest/core/internal/browser-runtime'),
   );
 
   const rstestInternalAliases = {
@@ -1268,7 +1276,7 @@ const createBrowserRuntime = async ({
     '@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,
+    '@rstest/core/internal/browser-runtime': browserRuntimePath,
     '@sinonjs/fake-timers': resolveBrowserFile('client/fakeTimersStub.ts'),
   };
 
@@ -1329,6 +1337,13 @@ const createBrowserRuntime = async ({
                 project.rootPath,
               ),
             );
+            // rspack `define` replaces `process.env` / `import.meta.env` with
+            // this literal expression. JSON.stringify reproduces the exact
+            // double-quoted `"rstest.env"` text, so the owned key can never
+            // drift from the runtime `Symbol.for(RSTEST_ENV_SYMBOL_KEY)` sites.
+            const rstestEnvDefine = `globalThis[Symbol.for(${JSON.stringify(
+              RSTEST_ENV_SYMBOL_KEY,
+            )})]`;
             // Merge order: current config -> userConfig -> rstest required config (highest priority)
             const merged = mergeEnvironmentConfig(
               config,
@@ -1347,8 +1362,8 @@ const createBrowserRuntime = async ({
                 },
                 source: {
                   define: {
-                    'process.env': 'globalThis[Symbol.for("rstest.env")]',
-                    'import.meta.env': 'globalThis[Symbol.for("rstest.env")]',
+                    'process.env': rstestEnvDefine,
+                    'import.meta.env': rstestEnvDefine,
                   },
                 },
                 output: {
@@ -1677,7 +1692,7 @@ const createBrowserRuntime = async ({
 };
 
 async function resolveProjectEntries(
-  context: Rstest,
+  context: RstestContext,
   shardedEntries?: Map<string, { entries: Record<string, string> }>,
 ): Promise<BrowserProjectEntries[]> {
   if (shardedEntries) {
@@ -1707,7 +1722,7 @@ async function resolveProjectEntries(
 // ============================================================================
 
 export const runBrowserController = async (
-  context: Rstest,
+  context: RstestContext,
   options?: BrowserTestRunOptions,
 ): Promise<BrowserTestRunResult | void> => {
   const {
@@ -2073,7 +2088,9 @@ export const runBrowserController = async (
 
   // Get max testTimeout from all browser projects for RPC timeout
   const maxTestTimeoutForRpc = Math.max(
-    ...browserProjects.map((p) => p.normalizedConfig.testTimeout ?? 5000),
+    ...browserProjects.map(
+      (p) => p.normalizedConfig.testTimeout ?? DEFAULT_TEST_TIMEOUT,
+    ),
   );
 
   const hostOptions: BrowserHostConfig = {
@@ -2161,13 +2178,16 @@ export const runBrowserController = async (
     }
   };
 
-  runtime.dispatchHandlers.set('browser', async (dispatchRequest) => {
-    const request = validateBrowserRpcRequest(dispatchRequest.args);
-    return dispatchBrowserRpcRequest({
-      request,
-      target: dispatchRequest.target,
-    });
-  });
+  runtime.dispatchHandlers.set(
+    DISPATCH_NAMESPACE_BROWSER,
+    async (dispatchRequest) => {
+      const request = validateBrowserRpcRequest(dispatchRequest.args);
+      return dispatchBrowserRpcRequest({
+        request,
+        target: dispatchRequest.target,
+      });
+    },
+  );
 
   runtime.setContainerOptions(hostOptions);
 
@@ -2397,7 +2417,9 @@ export const runBrowserController = async (
   };
 
   const shouldEmitUserConsoleLog = (log: UserConsoleLog): boolean => {
-    return context.normalizedConfig.onConsoleLog?.(log.content) !== false;
+    return (
+      context.normalizedConfig.onConsoleLog?.(log.content, log.type) !== false
+    );
   };
 
   const emitUserConsoleLog = async (log: UserConsoleLog): Promise<void> => {
@@ -2505,8 +2527,12 @@ export const runBrowserController = async (
         );
       case 'removeSnapshotFile':
         return snapshotRpcMethods.removeSnapshotFile(request.args.filepath);
-      default:
-        return undefined;
+      default: {
+        // Exhaustiveness guard: a new SnapshotRpcRequest method without a case
+        // here fails to compile rather than silently returning undefined.
+        const _exhaustive: never = request;
+        return _exhaustive;
+      }
     }
   };
 
@@ -2596,7 +2622,7 @@ export const runBrowserController = async (
       message: BrowserClientMessage,
     ): Promise<void> => {
       const response = await dispatchRouter.dispatch({
-        requestId: nextDispatchRequestId('runner'),
+        requestId: nextDispatchRequestId(DISPATCH_NAMESPACE_RUNNER),
         runToken: run.token,
         namespace: DISPATCH_NAMESPACE_RUNNER,
         method: message.type,
@@ -2653,7 +2679,7 @@ export const runBrowserController = async (
       );
       const perFileTimeoutMs =
         (projectRuntime?.runtimeConfig.testTimeout ?? maxTestTimeoutForRpc) +
-        30_000;
+        PER_FILE_TIMEOUT_BUFFER_MS;
 
       let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
@@ -3052,6 +3078,12 @@ export const runBrowserController = async (
   }
 
   let currentTestFiles = allTestFiles;
+  // Coincidentally equal to the runner-side CONFIG_WAIT_TIMEOUT_MS and
+  // DEFAULT_RPC_TIMEOUT_MS (client/entry.ts, client/dispatchTransport.ts) but
+  // semantically distinct and in a different runtime, so deliberately NOT shared
+  // with them. Invariant worth preserving: a runner must be able to receive its
+  // config (config-wait) before the host declares its frames un-ready, i.e.
+  // CONFIG_WAIT_TIMEOUT_MS <= RUNNER_FRAMES_READY_TIMEOUT_MS.
   const RUNNER_FRAMES_READY_TIMEOUT_MS = 30_000;
   let currentRunnerFramesSignature: string | null = null;
   const runnerFramesWaiters = new Map<string, Set<() => void>>();
@@ -3139,7 +3171,7 @@ export const runBrowserController = async (
     );
     return (
       (projectRuntime?.runtimeConfig.testTimeout ?? maxTestTimeoutForRpc) +
-      30_000
+      PER_FILE_TIMEOUT_BUFFER_MS
     );
   };
 
@@ -3602,7 +3634,7 @@ export type ListBrowserTestsResult = {
  * and collects their test structure (describe/test declarations).
  */
 export const listBrowserTests = async (
-  context: Rstest,
+  context: RstestContext,
   options?: {
     shardedEntries?: Map<string, { entries: Record<string, string> }>;
   },
@@ -3681,7 +3713,9 @@ export const listBrowserTests = async (
 
   // Get max testTimeout from all browser projects for RPC timeout
   const maxTestTimeoutForRpc = Math.max(
-    ...browserProjects.map((p) => p.normalizedConfig.testTimeout ?? 5000),
+    ...browserProjects.map(
+      (p) => p.normalizedConfig.testTimeout ?? DEFAULT_TEST_TIMEOUT,
+    ),
   );
 
   const hostOptions: BrowserHostConfig = {

package/src/index.ts

@@ -1,34 +1,45 @@
 import type {
+  BrowserHostModule,
   BrowserTestRunOptions,
   BrowserTestRunResult,
-  Rstest,
-} from '@rstest/core/browser';
+  RstestContext,
+} from '@rstest/core/internal/browser';
+import { validateBrowserConfig } from './configValidation';
 import {
   type ListBrowserTestsResult,
   listBrowserTests as listBrowserTestsImpl,
   runBrowserController,
 } from './hostController';
 
-export { validateBrowserConfig } from './configValidation';
-export {
-  BROWSER_VIEWPORT_PRESET_DIMENSIONS,
-  BROWSER_VIEWPORT_PRESET_IDS,
-  resolveBrowserViewportPreset,
-} from './viewportPresets';
+export { validateBrowserConfig };
 
 export async function runBrowserTests(
-  context: Rstest,
+  context: RstestContext,
   options?: BrowserTestRunOptions,
 ): Promise<BrowserTestRunResult | void> {
   return runBrowserController(context, options);
 }
 
 export async function listBrowserTests(
-  context: Rstest,
+  context: RstestContext,
+  options?: Pick<BrowserTestRunOptions, 'shardedEntries'>,
 ): Promise<ListBrowserTestsResult> {
-  return listBrowserTestsImpl(context);
+  // Forward `options` (e.g. `shardedEntries`) so `rstest list --shard` lists
+  // only the current shard's browser test files, matching the run path.
+  return listBrowserTestsImpl(context, options);
 }
 
+/**
+ * Compile-time guard: ensure the public host exports satisfy the core-owned
+ * {@link BrowserHostModule} contract. This catches drift such as a dropped
+ * `options` argument at the load boundary. No runtime side effect.
+ */
+void ({
+  validateBrowserConfig,
+  runBrowserTests,
+  listBrowserTests,
+} satisfies BrowserHostModule);
+
 export type {
   BrowserTestRunOptions,
   BrowserTestRunResult,