@rstest/browser 0.10.3 → 0.10.5

package/src/client/dispatchTransport.ts

@@ -4,10 +4,15 @@ import type {
 } from '../protocol';
 import {
   DISPATCH_MESSAGE_TYPE,
+  DISPATCH_NAMESPACE_RUNNER,
   DISPATCH_RESPONSE_TYPE,
+  DISPATCH_RPC_BRIDGE_NAME,
   DISPATCH_RPC_REQUEST_TYPE,
 } from '../protocol';
 
+// Coincidentally equal to the host-side RUNNER_FRAMES_READY_TIMEOUT_MS and the
+// runner's CONFIG_WAIT_TIMEOUT_MS (entry.ts), but a semantically distinct
+// default in a different runtime, so deliberately not shared with them.
 const DEFAULT_RPC_TIMEOUT_MS = 30_000;
 
 export const getRpcTimeout = (): number => {
@@ -37,6 +42,63 @@ export const createRequestId = (prefix: string): string => {
   return `${prefix}-${Date.now().toString(36)}-${requestIdCounter.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 };
 
+/**
+ * Build a runner-lifecycle dispatch request.
+ *
+ * Lifecycle events (`file-ready`, `suite-start`, `suite-result`, `case-start`)
+ * share the dispatch-rpc envelope but are delivered fire-and-forget via
+ * {@link sendRunnerLifecycle}, so the request id only needs to be unique — it is
+ * produced by the shared {@link createRequestId} factory rather than a bespoke
+ * per-runner counter.
+ */
+export const createRunnerLifecycleRequest = (
+  method: string,
+  args: unknown,
+): BrowserDispatchRequest => ({
+  requestId: createRequestId('runner-lifecycle'),
+  namespace: DISPATCH_NAMESPACE_RUNNER,
+  method,
+  args,
+});
+
+/**
+ * Deliver a runner-lifecycle request fire-and-forget.
+ *
+ * Unlike {@link dispatchRpc}, this never awaits, unwraps, id-matches, or times
+ * out: the host echoes a response but the runner ignores it. Failures surface
+ * only through the optional `onError` hook (debug logging at the call site),
+ * keeping the hot test loop non-blocking.
+ */
+export const sendRunnerLifecycle = (
+  request: BrowserDispatchRequest,
+  onError?: (error: unknown) => void,
+): void => {
+  if (window.parent === window) {
+    const dispatchBridge = window[DISPATCH_RPC_BRIDGE_NAME];
+    if (!dispatchBridge) {
+      onError?.(
+        new Error('Dispatch RPC bridge is not available in top-level runner.'),
+      );
+      return;
+    }
+    void Promise.resolve(dispatchBridge(request)).catch((error: unknown) => {
+      onError?.(error);
+    });
+    return;
+  }
+
+  window.parent.postMessage(
+    {
+      type: DISPATCH_MESSAGE_TYPE,
+      payload: {
+        type: DISPATCH_RPC_REQUEST_TYPE,
+        payload: request,
+      },
+    },
+    '*',
+  );
+};
+
 const isDispatchResponse = (
   value: unknown,
 ): value is BrowserDispatchResponse => {
@@ -116,7 +178,7 @@ export const dispatchRpc = <T>({
   staleMessage: string;
 }): Promise<T> => {
   if (window.parent === window) {
-    const dispatchBridge = window.__rstest_dispatch_rpc__;
+    const dispatchBridge = window[DISPATCH_RPC_BRIDGE_NAME];
     if (!dispatchBridge) {
       throw new Error(
         'Dispatch RPC bridge is not available in top-level runner.',

package/src/client/entry.ts

@@ -12,25 +12,26 @@ import type {
   RunnerHooks,
   RuntimeConfig,
   WorkerState,
-} from '@rstest/core/browser-runtime';
+} from '@rstest/core/internal/browser-runtime';
 import {
   createBrowserTaskContext,
   createRstestRuntime,
   globalApis,
+  RSTEST_ENV_SYMBOL_KEY,
   setRealTimers,
-} from '@rstest/core/browser-runtime';
+  unwrapRegex,
+} from '@rstest/core/internal/browser-runtime';
 import { normalize } from 'pathe';
 import type {
   BrowserClientMessage,
-  BrowserDispatchRequest,
   BrowserProjectRuntime,
+  RunnerLifecycleMethod,
 } from '../protocol';
+import { DISPATCH_MESSAGE_TYPE, RSTEST_CONFIG_MESSAGE_TYPE } from '../protocol';
 import {
-  DISPATCH_MESSAGE_TYPE,
-  DISPATCH_NAMESPACE_RUNNER,
-  DISPATCH_RPC_REQUEST_TYPE,
-  RSTEST_CONFIG_MESSAGE_TYPE,
-} from '../protocol';
+  createRunnerLifecycleRequest,
+  sendRunnerLifecycle,
+} from './dispatchTransport';
 import { BrowserSnapshotEnvironment } from './snapshot';
 import {
   findNewScriptUrl,
@@ -44,14 +45,6 @@ declare global {
   var __coverage__: Record<string, unknown> | undefined;
 }
 
-type RunnerLifecycleMethod =
-  | 'file-ready'
-  | 'suite-start'
-  | 'suite-result'
-  | 'case-start';
-
-let runnerDispatchRequestId = 0;
-
 /**
  * Debug logger for browser client.
  * Only logs when debug mode is enabled (DEBUG=rstest on server side).
@@ -63,27 +56,13 @@ const debugLog = (...args: unknown[]): void => {
 };
 
 type RuntimeEnvStore = Record<string, string | undefined>;
-const RSTEST_ENV_SYMBOL = Symbol.for('rstest.env');
+const RSTEST_ENV_SYMBOL = Symbol.for(RSTEST_ENV_SYMBOL_KEY);
 
 type GlobalWithRuntimeEnv = typeof globalThis &
   Record<symbol, unknown> & {
     global?: typeof globalThis;
   };
 
-const REGEXP_FLAG_PREFIX = 'RSTEST_REGEXP:';
-
-const unwrapRegex = (value: string): string | RegExp => {
-  if (value.startsWith(REGEXP_FLAG_PREFIX)) {
-    const raw = value.slice(REGEXP_FLAG_PREFIX.length);
-    const match = raw.match(/^\/(.+)\/([gimuy]*)$/);
-    if (match) {
-      const [, pattern, flags] = match;
-      return new RegExp(pattern!, flags);
-    }
-  }
-  return value;
-};
-
 const restoreRuntimeConfig = (
   config: BrowserProjectRuntime['runtimeConfig'],
 ): RuntimeConfig => {
@@ -230,42 +209,30 @@ const send = (message: BrowserClientMessage): void => {
   }
   // Fallback: direct call if running outside iframe (not typical)
   // Note: This binding may not exist if not using Playwright
-  window.__rstest_dispatch__?.(message);
+  window[DISPATCH_MESSAGE_TYPE]?.(message);
 };
 
 const dispatchRunnerLifecycle = (
   method: RunnerLifecycleMethod,
   payload: unknown,
 ): void => {
-  const request: BrowserDispatchRequest = {
-    requestId: `runner-lifecycle-${++runnerDispatchRequestId}`,
-    namespace: DISPATCH_NAMESPACE_RUNNER,
-    method,
-    args: payload,
-  };
-
-  if (window.parent === window) {
-    const dispatchBridge = window.__rstest_dispatch_rpc__;
-    if (!dispatchBridge) {
-      debugLog(
-        '[Runner] Missing dispatch bridge for lifecycle method:',
-        method,
-      );
-      return;
-    }
-    void Promise.resolve(dispatchBridge(request)).catch((error: unknown) => {
+  sendRunnerLifecycle(
+    createRunnerLifecycleRequest(method, payload),
+    (error: unknown) => {
       debugLog('[Runner] Failed to dispatch lifecycle method:', method, error);
-    });
-    return;
-  }
-
-  send({
-    type: DISPATCH_RPC_REQUEST_TYPE,
-    payload: request,
-  });
+    },
+  );
 };
 
-/** Timeout for waiting for browser config from container (30 seconds) */
+/**
+ * Timeout for waiting for browser config from container (30 seconds).
+ *
+ * Coincidentally equal to the RPC default (client/dispatchTransport.ts) and the
+ * host's RUNNER_FRAMES_READY_TIMEOUT_MS (hostController.ts), but semantically
+ * distinct and in a different runtime, so deliberately not shared. Implicit
+ * invariant: this must not exceed the host's frames-ready timeout, or the host
+ * declares the runner un-ready before it can even receive its config.
+ */
 const CONFIG_WAIT_TIMEOUT_MS = 30_000;
 
 /**

package/src/client/public.ts

@@ -1,12 +1,12 @@
 /**
- * Re-export runtime API from @rstest/core/browser-runtime for browser use.
+ * Re-export runtime API from @rstest/core/internal/browser-runtime for browser use.
  * This file is used as an alias target for '@rstest/core' in browser mode.
  *
- * Uses @rstest/core/browser-runtime which only exports the test APIs
+ * Uses @rstest/core/internal/browser-runtime which only exports the test APIs
  * (describe, it, expect, etc.) without any Node.js dependencies.
  */
 
 // Re-export types from @rstest/core (these are compile-time only)
 export type { Assertion, Mock } from '@rstest/core';
 // Re-export all public test APIs
-export * from '@rstest/core/browser-runtime';
+export * from '@rstest/core/internal/browser-runtime';

package/src/client/snapshot.ts

@@ -1,4 +1,4 @@
-import type { BrowserDispatchRequest, SnapshotRpcRequest } from '../protocol';
+import type { BrowserDispatchRequest, SnapshotRpcCall } from '../protocol';
 import { DISPATCH_NAMESPACE_SNAPSHOT } from '../protocol';
 import {
   createRequestId,
@@ -11,41 +11,36 @@ const SNAPSHOT_HEADER = '// Rstest Snapshot';
 
 const createSnapshotDispatchRequest = (
   requestId: string,
-  method: SnapshotRpcRequest['method'],
-  args: SnapshotRpcRequest['args'],
+  call: SnapshotRpcCall,
 ): BrowserDispatchRequest => {
   // Snapshot is just one namespace on the shared dispatch RPC channel.
   // Keep this mapping explicit so new runner-side RPC clients can mirror it.
   return {
     requestId,
     namespace: DISPATCH_NAMESPACE_SNAPSHOT,
-    method,
-    args,
+    method: call.method,
+    args: call.args,
   };
 };
 
 /**
  * Send a snapshot RPC request to the container (parent window).
  * The container will forward it to the host via WebSocket RPC.
+ *
+ * `call` is a {@link SnapshotRpcCall}, so `method` and `args` are validated as a
+ * pair — a mismatched argument shape fails to compile at the call site.
  */
-const sendRpcRequest = <T>(
-  method: SnapshotRpcRequest['method'],
-  args: SnapshotRpcRequest['args'],
-): Promise<T> => {
+const sendRpcRequest = <T>(call: SnapshotRpcCall): Promise<T> => {
   const requestId = createRequestId('snapshot-rpc');
   const rpcTimeout = getRpcTimeout();
-  const dispatchRequest = createSnapshotDispatchRequest(
-    requestId,
-    method,
-    args,
-  );
+  const dispatchRequest = createSnapshotDispatchRequest(requestId, call);
 
   return dispatchRpc<T>({
     requestId,
     request: dispatchRequest,
     timeoutMs: rpcTimeout,
     staleMessage: 'Stale snapshot RPC request ignored.',
-    timeoutMessage: `Snapshot RPC timeout after ${rpcTimeout / 1000}s: ${method}`,
+    timeoutMessage: `Snapshot RPC timeout after ${rpcTimeout / 1000}s: ${call.method}`,
   });
 };
 
@@ -67,8 +62,9 @@ export class BrowserSnapshotEnvironment {
   }
 
   async resolvePath(filepath: string): Promise<string> {
-    return sendRpcRequest<string>('resolveSnapshotPath', {
-      testPath: filepath,
+    return sendRpcRequest<string>({
+      method: 'resolveSnapshotPath',
+      args: { testPath: filepath },
     });
   }
 
@@ -77,18 +73,24 @@ export class BrowserSnapshotEnvironment {
   }
 
   async saveSnapshotFile(filepath: string, snapshot: string): Promise<void> {
-    await sendRpcRequest<void>('saveSnapshotFile', {
-      filepath,
-      content: snapshot,
+    await sendRpcRequest<void>({
+      method: 'saveSnapshotFile',
+      args: { filepath, content: snapshot },
     });
   }
 
   async readSnapshotFile(filepath: string): Promise<string | null> {
-    return sendRpcRequest<string | null>('readSnapshotFile', { filepath });
+    return sendRpcRequest<string | null>({
+      method: 'readSnapshotFile',
+      args: { filepath },
+    });
   }
 
   async removeSnapshotFile(filepath: string): Promise<void> {
-    await sendRpcRequest<void>('removeSnapshotFile', { filepath });
+    await sendRpcRequest<void>({
+      method: 'removeSnapshotFile',
+      args: { filepath },
+    });
   }
 
   /**

package/src/client/sourceMapSupport.ts

@@ -102,7 +102,7 @@ export const preloadTestFileSourceMap = async (
  * Preload source map for the runner.js file.
  *
  * This is essential for inline snapshot support because the snapshot code
- * runs in runner.js (which contains @rstest/core/browser-runtime).
+ * runs in runner.js (which contains @rstest/core/internal/browser-runtime).
  * Without this, stack traces from inline snapshots cannot be mapped back
  * to the original source files.
  */

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,27 +17,9 @@ 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(),
+  numCpus: number = getNumCpus(),
 ): number => {
   const baseWorkers = Math.max(
     Math.min(DEFAULT_MAX_HEADLESS_WORKERS, numCpus - 1),

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/headedSerialTaskQueue.ts

@@ -1,10 +1,14 @@
 type HeadedSerialTask = () => Promise<void>;
 
+type HeadedSerialTaskQueue = {
+  enqueue: (task: HeadedSerialTask) => Promise<void>;
+};
+
 /**
  * Serializes headed browser file execution so only one task runs at a time.
  * The queue keeps draining even if an earlier task rejects.
  */
-export const createHeadedSerialTaskQueue = () => {
+export const createHeadedSerialTaskQueue = (): HeadedSerialTaskQueue => {
   let queue: Promise<void> = Promise.resolve();
 
   const enqueue = (task: HeadedSerialTask): Promise<void> => {