refactor(core): move internal browser host subpaths under ./internal

fi3ework · fi3ework · commit eced70785c04 · 2026-06-02T15:10:40.000+08:00
Rename @rstest/core's `./browser` and `./browser-runtime` exports to
`./internal/browser` and `./internal/browser-runtime`. Both subpaths are
consumed only by first-party packages (@rstest/browser, @rstest/browser-ui)
and are JSDoc-marked "not part of the public API"; the `internal/` prefix
makes the path name match that non-public reality. The two paths stay
separate: `./internal/browser` carries Node-only deps while
`./internal/browser-runtime` is browser-safe.

Also retarget core's ambient module declaration for the browser host
entries from `@rstest/browser` to `@rstest/browser/internal`, matching the
subpath the runtime actually loads via browserLoader.
diff --git a/knip.jsonc b/knip.jsonc
@@ -32,7 +32,7 @@
     },
     "packages/core": {
       "entry": [
-        // Package export: "./browser-runtime" (separate rslib env targeting web)
+        // Package export: "./internal/browser-runtime" (separate rslib env targeting web)
         "src/browserRuntime.ts",
         // Worker entries bundled by rslib
         "src/runtime/worker/index.ts",
diff --git a/packages/browser-ui/src/core/caseMap.test.ts b/packages/browser-ui/src/core/caseMap.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from '@rstest/core';
-import type { TestInfo } from '@rstest/core/browser-runtime';
+import type { TestInfo } from '@rstest/core/internal/browser-runtime';
 import type { CaseInfo } from '../utils/constants';
 import { buildCollectedCaseMap, upsertRunningCase } from './caseMap';
 
diff --git a/packages/browser-ui/src/core/caseMap.ts b/packages/browser-ui/src/core/caseMap.ts
@@ -1,4 +1,4 @@
-import type { TestInfo } from '@rstest/core/browser-runtime';
+import type { TestInfo } from '@rstest/core/internal/browser-runtime';
 import type { CaseInfo } from '../utils/constants';
 
 type CollectedCaseInfo = Extract<TestInfo, { type: 'case' }>;
diff --git a/packages/browser-ui/src/types.ts b/packages/browser-ui/src/types.ts
@@ -12,7 +12,7 @@ import type {
   TestFileResult,
   TestInfo,
   TestResult,
-} from '@rstest/core/browser-runtime';
+} from '@rstest/core/internal/browser-runtime';
 
 /**
  * Browser UI types
diff --git a/packages/browser-ui/src/utils/viewportPresets.ts b/packages/browser-ui/src/utils/viewportPresets.ts
@@ -2,7 +2,7 @@ import {
   BROWSER_VIEWPORT_PRESET_DIMENSIONS,
   BROWSER_VIEWPORT_PRESET_IDS,
 } from '@rstest/browser/viewport-presets';
-import type { DevicePreset } from '@rstest/core/browser';
+import type { DevicePreset } from '@rstest/core/internal/browser';
 
 export type { DevicePreset };
 
diff --git a/packages/browser/AGENTS.md b/packages/browser/AGENTS.md
@@ -105,7 +105,7 @@ pnpm --filter @rstest/browser typecheck
 
 ## Dependencies
 
-This package requires `@rstest/core` as a peer dependency. The browser client code uses internal APIs from `@rstest/core/browser`:
+This package requires `@rstest/core` as a peer dependency. The browser client code uses internal APIs from `@rstest/core/internal/browser`:
 
 - `createRstestRuntime` - Creates test runtime
 - `setRealTimers` - Preserves real timer references
diff --git a/packages/browser/rslib.config.ts b/packages/browser/rslib.config.ts
@@ -30,7 +30,7 @@ export default defineConfig({
         externals: {
           // Keep @rstest/core as external
           '@rstest/core': '@rstest/core',
-          '@rstest/core/browser': '@rstest/core/browser',
+          '@rstest/core/internal/browser': '@rstest/core/internal/browser',
           // Keep @rsbuild/core as external (provided by @rstest/core)
           '@rsbuild/core': '@rsbuild/core',
         },
diff --git a/packages/browser/src/client/entry.ts b/packages/browser/src/client/entry.ts
@@ -12,13 +12,13 @@ import type {
   RunnerHooks,
   RuntimeConfig,
   WorkerState,
-} from '@rstest/core/browser-runtime';
+} from '@rstest/core/internal/browser-runtime';
 import {
   createBrowserTaskContext,
   createRstestRuntime,
   globalApis,
   setRealTimers,
-} from '@rstest/core/browser-runtime';
+} from '@rstest/core/internal/browser-runtime';
 import { normalize } from 'pathe';
 import type {
   BrowserClientMessage,
diff --git a/packages/browser/src/client/public.ts b/packages/browser/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';
diff --git a/packages/browser/src/client/sourceMapSupport.ts b/packages/browser/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.
  */
diff --git a/packages/browser/src/concurrency.ts b/packages/browser/src/concurrency.ts
@@ -1,5 +1,5 @@
 import os from 'node:os';
-import type { Rstest } from '@rstest/core/browser';
+import type { Rstest } from '@rstest/core/internal/browser';
 
 // Shared headless concurrency policy.
 // Keep this in one place so executors reuse the same worker semantics.
diff --git a/packages/browser/src/configValidation.ts b/packages/browser/src/configValidation.ts
@@ -1,4 +1,4 @@
-import type { Rstest } from '@rstest/core/browser';
+import type { Rstest } from '@rstest/core/internal/browser';
 import { resolveBrowserViewportPreset } from './viewportPresets';
 
 const SUPPORTED_PROVIDERS = ['playwright'] as const;
diff --git a/packages/browser/src/dispatchCapabilities.ts b/packages/browser/src/dispatchCapabilities.ts
@@ -1,4 +1,4 @@
-import type { Reporter } from '@rstest/core/browser';
+import type { Reporter } from '@rstest/core/internal/browser';
 import { HostDispatchRouter } from './dispatchRouter';
 import type {
   BrowserClientMessage,
diff --git a/packages/browser/src/hostController.ts b/packages/browser/src/hostController.ts
@@ -31,7 +31,7 @@ import {
   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';
@@ -1257,7 +1257,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 +1268,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'),
   };
 
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -2,7 +2,7 @@ import type {
   BrowserTestRunOptions,
   BrowserTestRunResult,
   Rstest,
-} from '@rstest/core/browser';
+} from '@rstest/core/internal/browser';
 import {
   type ListBrowserTestsResult,
   listBrowserTests as listBrowserTestsImpl,
diff --git a/packages/browser/src/protocol.ts b/packages/browser/src/protocol.ts
@@ -1,10 +1,10 @@
-import type { DevicePreset } from '@rstest/core/browser';
+import type { DevicePreset } from '@rstest/core/internal/browser';
 import type {
   RuntimeConfig,
   TestFileResult,
   TestInfo,
   TestResult,
-} from '@rstest/core/browser-runtime';
+} from '@rstest/core/internal/browser-runtime';
 import type { SnapshotUpdateState } from '@vitest/snapshot';
 
 export type {
diff --git a/packages/browser/src/watchCliShortcuts.ts b/packages/browser/src/watchCliShortcuts.ts
@@ -1,4 +1,4 @@
-import { color, logger } from '@rstest/core/browser';
+import { color, logger } from '@rstest/core/internal/browser';
 
 const isTTY = (): boolean => Boolean(process.stdin.isTTY && !process.env.CI);
 
diff --git a/packages/browser/tests/hostController.test.ts b/packages/browser/tests/hostController.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from '@rstest/core';
-import type { ProjectContext, Rstest } from '@rstest/core/browser';
+import type { ProjectContext, Rstest } from '@rstest/core/internal/browser';
 import {
   createBrowserLazyCompilationConfig,
   createBrowserRsbuildDevConfig,
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -27,11 +27,11 @@
       "types": "./dist/api/index.d.ts",
       "default": "./dist/api/index.js"
     },
-    "./browser": {
+    "./internal/browser": {
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
     },
-    "./browser-runtime": {
+    "./internal/browser-runtime": {
       "types": "./dist/browser-runtime/index.d.ts",
       "default": "./dist/browser-runtime/index.js"
     },
diff --git a/packages/core/src/env.d.ts b/packages/core/src/env.d.ts
@@ -5,10 +5,12 @@ declare const RSTEST_SELF_CI: boolean;
 declare const PLAYWRIGHT_VERSION: string;
 
 /**
- * Module declaration for @rstest/browser (optional peer dependency).
+ * Module declaration for @rstest/browser/internal (optional peer dependency).
+ * These host-side entries live on the `./internal` subpath, not the public `.`
+ * entry; core loads them via `@rstest/browser/internal` (see browserLoader.ts).
  * The actual types come from the package when installed.
  */
-declare module '@rstest/browser' {
+declare module '@rstest/browser/internal' {
   import type { ListCommandResult, RstestContext } from './types';
 
   export function validateBrowserConfig(context: RstestContext): void;

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { TestInfo } from '@rstest/core/browser-runtime';`
	`1`	`+import type { TestInfo } from '@rstest/core/internal/browser-runtime';`
`2`	`2`	`import type { CaseInfo } from '../utils/constants';`
`3`	`3`
`4`	`4`	`type CollectedCaseInfo = Extract<TestInfo, { type: 'case' }>;`
Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,7 @@ export const preloadTestFileSourceMap = async (`
`102`	`102`	`* Preload source map for the runner.js file.`
`103`	`103`	`*`
`104`	`104`	`* This is essential for inline snapshot support because the snapshot code`
`105`		`- * runs in runner.js (which contains @rstest/core/browser-runtime).`
	`105`	`+ * runs in runner.js (which contains @rstest/core/internal/browser-runtime).`
`106`	`106`	`* Without this, stack traces from inline snapshots cannot be mapped back`
`107`	`107`	`* to the original source files.`
`108`	`108`	`*/`