vinext 1.2.0 → 1.3.0

package/README.md

@@ -232,6 +232,8 @@ The migration is non-destructive -- your existing Next.js setup continues to wor
 
 vinext targets Vite 8, which defaults to Rolldown, Oxc, Lightning CSS, and a newer browser baseline. If you bring custom Vite config or plugins from an older setup, prefer `oxc`, `optimizeDeps.rolldownOptions`, and `build.rolldownOptions` over older `esbuild` and `build.rollupOptions` knobs, and override `build.target` if you still need older browsers. If a dependency breaks because of stricter CommonJS default import handling, fix the import or use `legacy.inconsistentCjsInterop: true` as a temporary escape hatch. See the [Vite 8 migration guide](https://vite.dev/guide/migration).
 
+Production client JS, Web Worker and CSS files use hash-only file names (by default `_next/static/chunks/[hash].js`, `_next/static/workers/<module-id>-[hash].js` and `_next/static/css/[hash].css`) so component and source file names don't appear in public asset URLs. Web Worker file names are fixed. To use different client JS and CSS names, set `entryFileNames`, `chunkFileNames` or `assetFileNames` in `build.rolldownOptions.output` (or `environments.client.build.rolldownOptions.output`), keeping them under the client assets directory: `_next/static/` by default, or `<prefix>/_next/static/` with a path-based `assetPrefix` such as `/cdn` (e.g. `chunkFileNames: "cdn/_next/static/chunks/[name]-[hash].js"`).
+
 ```bash
 npm run dev:vinext    # Start the vinext dev server (port 3001)
 npm run build:vinext  # Build production output with vinext
@@ -677,15 +679,16 @@ Every `next/*` import is shimmed to a Vite-compatible implementation.
 
 ### Configuration
 
-| Feature                                          |     | Notes                                                                                                                                                                                                                  |
-| ------------------------------------------------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `next.config.js` / `.ts` / `.mjs`                | ✅  | Function configs, phase argument                                                                                                                                                                                       |
-| `rewrites` / `redirects` / `headers`             | ✅  | All phases, param interpolation                                                                                                                                                                                        |
-| Environment variables (`.env*`, `NEXT_PUBLIC_*`) | ✅  | Auto-loads Next.js-style dotenv files; only public vars are inlined                                                                                                                                                    |
-| `images` config                                  | 🟡  | Parsed but not used for optimization                                                                                                                                                                                   |
-| `experimental.optimizePackageImports`            | ✅  | Rewrites barrel imports to direct sub-module imports in RSC/SSR environments. A default set (lucide-react, date-fns, radix-ui, antd, MUI, and others) are always optimized. Add package names here to extend the list. |
-| `vinext({ nextConfig })`                         | ✅  | Inline Next-style config from `vite.config.*`. Supports object-form and function-form config. When provided, this overrides root `next.config.*`.                                                                      |
-| `vinext({ react: { compiler: true } })`          | ✅  | React Compiler auto memoization. Needs `@vitejs/plugin-react` 6.1+ and the optional `oxc-transform-react` package.                                                                                                     |
+| Feature                                          |     | Notes                                                                                                                                                                                                                                                    |
+| ------------------------------------------------ | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `next.config.js` / `.ts` / `.mjs`                | ✅  | Function configs, phase argument                                                                                                                                                                                                                         |
+| `rewrites` / `redirects` / `headers`             | ✅  | All phases, param interpolation. A source Next.js rejects fails config loading, as it fails the Next.js build: missing, not starting with `/`, over the 4,096-character built-regex limit, or rejected by path-to-regexp, such as a header glob `/api/*` |
+| Environment variables (`.env*`, `NEXT_PUBLIC_*`) | ✅  | Auto-loads Next.js-style dotenv files; only public vars are inlined                                                                                                                                                                                      |
+| `images` config                                  | 🟡  | Parsed but not used for optimization                                                                                                                                                                                                                     |
+| `experimental.optimizePackageImports`            | ✅  | Rewrites barrel imports to direct sub-module imports in RSC/SSR environments. A default set (lucide-react, date-fns, radix-ui, antd, MUI, and others) are always optimized. Add package names here to extend the list.                                   |
+| `vinext({ nextConfig })`                         | ✅  | Inline Next-style config from `vite.config.*`. Supports object-form and function-form config. When provided, this overrides root `next.config.*`.                                                                                                        |
+| `vinext({ react: { compiler: true } })`          | ✅  | React Compiler auto memoization. Needs `@vitejs/plugin-react` 6.1+ and the optional `oxc-transform-react` package.                                                                                                                                       |
+| `vinext({ disableNextLikeChunking: true })`      | ✅  | Loads each client component from its own chunk, instead of one chunk per route group (Next.js-like; App Router production builds). Grouping also turns off on its own when the client build has other chunk groups.                                      |
 
 ### React Compiler
 
@@ -1048,7 +1051,7 @@ Or add it to your `package.json` as a file dependency:
 }
 ```
 
-vinext has peer dependencies on `react ^19.2.6`, `react-dom ^19.2.6`, `react-server-dom-webpack ^19.2.6`, and `vite ^8.0.0`. Then replace `next` with `vinext` in your scripts and run as normal.
+vinext has peer dependencies on `react ^19.3.1`, `react-dom ^19.3.1`, `react-server-dom-webpack ^19.3.1`, and `vite ^8.0.0`. Then replace `next` with `vinext` in your scripts and run as normal.
 
 ## Contributing
 

package/dist/build/client-build-config.d.ts

@@ -39,10 +39,62 @@ export declare function createClientAssetFileNames(assetsDir: string): (assetInf
  *   and route-specific code stays in route chunks.
  */
 export declare function createClientManualChunks(shimsDir: string, preserveRouteBoundaries?: boolean): (id: string) => string | undefined;
-export declare function createClientFileNameConfig(assetsDir: string): {
-  entryFileNames: string;
-  chunkFileNames: string;
+/**
+ * Web Worker output names. Workers are hash-only like client chunks, so their
+ * URLs don't publish source file names. Vite bundles each worker separately
+ * and stores the outputs by file name, so two workers' entries or chunks with
+ * identical code would share `[hash].js` and one's source map would overwrite
+ * the other's. Each name therefore also carries an opaque id derived from the
+ * chunk's module ids (root-relative for files).
+ */
+export declare function createWorkerFileNames(assetsDir: string, root: string): {
+  entryFileNames: (chunk: {
+    facadeModuleId: string | null;
+    moduleIds?: readonly string[];
+  }) => string;
+  chunkFileNames: (chunk: {
+    facadeModuleId: string | null;
+    moduleIds?: readonly string[];
+  }) => string;
 };
+/**
+ * vinext's client output file names, limited to the ones the incoming client
+ * environment config leaves unset. Vite merges `config` hook results over the
+ * user's config, so vinext applies these from `configEnvironment` instead: by
+ * then the user's top-level `build` and `environments.client.build` are merged
+ * into the client environment, and a user-provided pattern wins.
+ *
+ * Returns null for array-shaped output, which cannot be augmented without Vite
+ * concatenating a second output entry. Array-shaped client output is advanced
+ * config vinext doesn't support: Vite also appends vinext's own client output
+ * object (code splitting) to the user's array, producing an extra bundle.
+ */
+export declare function createClientOutputFileNameDefaults(output: VinextBuildBundlerOptions["output"], assetsDir: string): {
+  entryFileNames?: string | undefined;
+  chunkFileNames?: string | undefined;
+  assetFileNames?: ((assetInfo: ClientAssetFileNameInfo) => string) | undefined;
+} | null;
+/** Entry, chunk and asset file names from a (non-array) bundler output config. */
+export declare function getOutputFileNames(output: VinextBuildBundlerOptions["output"]): Pick<VinextBuildOutput, "entryFileNames" | "chunkFileNames" | "assetFileNames">;
+/**
+ * User-provided client file name patterns vinext cannot serve correctly:
+ * - outside `assetsDir`: built-asset URLs, immutable caching and
+ *   precompression all assume client output lives there;
+ * - without `[hash]`: everything under `assetsDir` is served
+ *   `immutable`, so an unhashed URL would pin stale code for a year;
+ * - JS not ending in `.js`: client metadata and Pages Router script
+ *   tags only recognize `.js` chunks;
+ * - assets not ending in `[extname]` (or `.[ext]`): CSS without its real
+ *   extension is served as `application/octet-stream` and rejected by browsers.
+ * - asset basenames not starting with `[name].` or `[name]-`: restoring CSS
+ *   `url()` assets deduplicated across builds swaps the source stem at the
+ *   start of the emitted basename (see css-url-assets.ts), so any other
+ *   placement or delimiter drops the hash from the restored sibling.
+ * This is a guard against common mistakes, not full validation: function
+ * patterns and array-shaped output are advanced config left to the user to
+ * keep within these rules.
+ */
+export declare function findUnsupportedClientOutputFileNames(output: VinextBuildBundlerOptions["output"], assetsDir: string): string[];
 export declare function createClientCodeSplittingConfig(clientManualChunks: (id: string) => string | undefined): {
   minSize: number;
   groups: {
@@ -126,4 +178,13 @@ export declare function assertClientOutDirIsSeparate(root: string, dirs: {
   rscOutDir?: string;
   ssrOutDir?: string;
 }): void;
+/**
+ * Whether client output options have chunk groups (`codeSplitting.groups`,
+ * `advancedChunks.groups` or `manualChunks`) other than vinext's own
+ * `ownGroups`, whether they came from the user or another plugin. vinext's
+ * client-reference route grouping is disabled in that case: a manual group can
+ * move modules out of a route group's chunk, and that combination has been
+ * seen to evaluate modules out of order and break hydration.
+ */
+export declare function hasUserClientChunkGroups(output: unknown, ownGroups: ReadonlySet<unknown>): boolean;
 //#endregion

package/dist/build/client-build-config.js

@@ -1,4 +1,7 @@
 import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
+import { stripViteModuleQuery } from "../utils/path.js";
+import { WORKER_IMAGE_METADATA_PREFIX } from "../plugins/worker-image-imports.js";
+import { createHash } from "node:crypto";
 //#region src/build/client-build-config.ts
 const ROUTE_OWNED_CLIENT_SHIMS = /* @__PURE__ */ new Set([
 	"app-router-tree-context",
@@ -7,6 +10,7 @@ const ROUTE_OWNED_CLIENT_SHIMS = /* @__PURE__ */ new Set([
 	"dynamic-preload-chunks",
 	"form",
 	"image",
+	"image-props",
 	"internal/hybrid-client-route-owner",
 	"layout-segment-context",
 	"legacy-image",
@@ -16,7 +20,7 @@ const ROUTE_OWNED_CLIENT_SHIMS = /* @__PURE__ */ new Set([
 	"script",
 	"web-vitals"
 ]);
-const NEXT_CLIENT_CSS_ASSET_FILE_NAMES = "css/[name].[hash:8][extname]";
+const NEXT_CLIENT_CSS_ASSET_FILE_NAMES = "css/[hash][extname]";
 const NEXT_CLIENT_STATIC_MEDIA_FILE_NAMES = "media/[name].[hash:8][extname]";
 function joinAssetFileNamePattern(assetsDir, pattern) {
 	let end = assetsDir.length;
@@ -110,13 +114,119 @@ function createClientManualChunks(shimsDir, preserveRouteBoundaries = false) {
 		}
 	};
 }
+/**
+* Client JS is emitted as hash-only `<assetsDir>/chunks/[hash].js`. Rolldown
+* names a chunk after its first module, so `[name]` would publish component
+* and source file names in public asset URLs. Next.js doesn't put component
+* names in production chunk URLs either: webpack names split chunks by
+* deterministic numeric id. Users can opt back into `[name]` through their own
+* Vite config; see createClientOutputFileNameDefaults.
+*/
 function createClientFileNameConfig(assetsDir) {
 	const chunksDir = `${assetsDir}/chunks`;
 	return {
-		entryFileNames: `${chunksDir}/[name]-[hash].js`,
-		chunkFileNames: `${chunksDir}/[name]-[hash].js`
+		entryFileNames: `${chunksDir}/[hash].js`,
+		chunkFileNames: `${chunksDir}/[hash].js`
 	};
 }
+/**
+* Web Worker output names. Workers are hash-only like client chunks, so their
+* URLs don't publish source file names. Vite bundles each worker separately
+* and stores the outputs by file name, so two workers' entries or chunks with
+* identical code would share `[hash].js` and one's source map would overwrite
+* the other's. Each name therefore also carries an opaque id derived from the
+* chunk's module ids (root-relative for files).
+*/
+function createWorkerFileNames(assetsDir, root) {
+	const workersDir = `${assetsDir}/workers`;
+	const fileName = (chunk) => {
+		const ids = chunk.facadeModuleId ? [chunk.facadeModuleId] : chunk.moduleIds ?? [];
+		const chunkId = JSON.stringify(ids.map((id) => {
+			const file = stripViteModuleQuery(id);
+			if (path.isAbsolute(file)) return ["file", toSlash(path.relative(root, file)) + id.slice(file.length)];
+			const imagePath = id.startsWith("\0vinext-worker-image-meta:") ? id.slice(WORKER_IMAGE_METADATA_PREFIX.length) : void 0;
+			if (imagePath !== void 0 && path.isAbsolute(imagePath)) return ["image-meta", toSlash(path.relative(root, imagePath))];
+			return ["id", id];
+		}));
+		const idHash = createHash("sha256").update(chunkId).digest("hex").slice(0, 8);
+		return `${workersDir}/${idHash}-[hash].js`;
+	};
+	return {
+		entryFileNames: fileName,
+		chunkFileNames: fileName
+	};
+}
+/**
+* vinext's client output file names, limited to the ones the incoming client
+* environment config leaves unset. Vite merges `config` hook results over the
+* user's config, so vinext applies these from `configEnvironment` instead: by
+* then the user's top-level `build` and `environments.client.build` are merged
+* into the client environment, and a user-provided pattern wins.
+*
+* Returns null for array-shaped output, which cannot be augmented without Vite
+* concatenating a second output entry. Array-shaped client output is advanced
+* config vinext doesn't support: Vite also appends vinext's own client output
+* object (code splitting) to the user's array, producing an extra bundle.
+*/
+function createClientOutputFileNameDefaults(output, assetsDir) {
+	if (Array.isArray(output)) return null;
+	const configured = output ?? {};
+	const { entryFileNames, chunkFileNames } = createClientFileNameConfig(assetsDir);
+	return {
+		...configured.entryFileNames === void 0 ? { entryFileNames } : {},
+		...configured.chunkFileNames === void 0 ? { chunkFileNames } : {},
+		...configured.assetFileNames === void 0 ? { assetFileNames: createClientAssetFileNames(assetsDir) } : {}
+	};
+}
+/** Entry, chunk and asset file names from a (non-array) bundler output config. */
+function getOutputFileNames(output) {
+	if (!output || Array.isArray(output)) return {};
+	const { entryFileNames, chunkFileNames, assetFileNames } = output;
+	return {
+		entryFileNames,
+		chunkFileNames,
+		assetFileNames
+	};
+}
+/**
+* User-provided client file name patterns vinext cannot serve correctly:
+* - outside `assetsDir`: built-asset URLs, immutable caching and
+*   precompression all assume client output lives there;
+* - without `[hash]`: everything under `assetsDir` is served
+*   `immutable`, so an unhashed URL would pin stale code for a year;
+* - JS not ending in `.js`: client metadata and Pages Router script
+*   tags only recognize `.js` chunks;
+* - assets not ending in `[extname]` (or `.[ext]`): CSS without its real
+*   extension is served as `application/octet-stream` and rejected by browsers.
+* - asset basenames not starting with `[name].` or `[name]-`: restoring CSS
+*   `url()` assets deduplicated across builds swaps the source stem at the
+*   start of the emitted basename (see css-url-assets.ts), so any other
+*   placement or delimiter drops the hash from the restored sibling.
+* This is a guard against common mistakes, not full validation: function
+* patterns and array-shaped output are advanced config left to the user to
+* keep within these rules.
+*/
+function findUnsupportedClientOutputFileNames(output, assetsDir) {
+	if (!output || Array.isArray(output)) return [];
+	const unsupported = [];
+	for (const key of [
+		"entryFileNames",
+		"chunkFileNames",
+		"assetFileNames"
+	]) {
+		const value = output[key];
+		if (typeof value !== "string") continue;
+		const problems = [
+			!value.startsWith(`${assetsDir}/`) && `outside "${assetsDir}/"`,
+			!value.includes("[hash") && "no [hash]",
+			key !== "assetFileNames" && !value.endsWith(".js") && "not \".js\"",
+			key === "assetFileNames" && !value.endsWith("[extname]") && !value.endsWith(".[ext]") && "not ending in [extname]",
+			key === "assetFileNames" && !/^\[name\][.-]/.test(value.slice(value.lastIndexOf("/") + 1)) && "basename not starting with \"[name].\" or \"[name]-\""
+		].filter(Boolean);
+		if (problems.length > 0) unsupported.push(`${key}: ${JSON.stringify(value)} (${problems.join(", ")})`);
+	}
+	return unsupported;
+}
 function createClientCodeSplittingConfig(clientManualChunks) {
 	return {
 		minSize: 1e4,
@@ -282,5 +392,22 @@ function assertClientOutDirIsSeparate(root, dirs) {
 		throw new Error(`[vinext] clientOutDir "${dirs.clientOutDir}" contains ${name} "${dir}". The client build runs last and empties its output directory, which would delete the server build. Use separate output directories.`);
 	}
 }
+function hasChunkGroups(output, ownGroups) {
+	if (!output || typeof output !== "object") return false;
+	const { advancedChunks, codeSplitting, manualChunks } = output;
+	if (manualChunks !== void 0) return true;
+	return [...advancedChunks?.groups ?? [], ...(codeSplitting && typeof codeSplitting === "object" ? codeSplitting.groups : void 0) ?? []].some((group) => !ownGroups.has(group));
+}
+/**
+* Whether client output options have chunk groups (`codeSplitting.groups`,
+* `advancedChunks.groups` or `manualChunks`) other than vinext's own
+* `ownGroups`, whether they came from the user or another plugin. vinext's
+* client-reference route grouping is disabled in that case: a manual group can
+* move modules out of a route group's chunk, and that combination has been
+* seen to evaluate modules out of order and break hydration.
+*/
+function hasUserClientChunkGroups(output, ownGroups) {
+	return Array.isArray(output) ? output.some((entry) => hasChunkGroups(entry, ownGroups)) : hasChunkGroups(output, ownGroups);
+}
 //#endregion
-export { RSC_FRAMEWORK_CHUNK_TEST, assertClientOutDirIsSeparate, createClientAssetFileNames, createClientCodeSplittingConfig, createClientFileNameConfig, createClientManualChunks, createMultiStageChunkFileNames, createMultiStageCodeSplittingConfig, createRscFrameworkChunkOutputConfig, getBuildBundlerOptions, getClientTreeshakeConfig, isRscFrameworkModule, sanitizeRscChunkFileName, withBuildBundlerOptions };
+export { RSC_FRAMEWORK_CHUNK_TEST, assertClientOutDirIsSeparate, createClientAssetFileNames, createClientCodeSplittingConfig, createClientManualChunks, createClientOutputFileNameDefaults, createMultiStageChunkFileNames, createMultiStageCodeSplittingConfig, createRscFrameworkChunkOutputConfig, createWorkerFileNames, findUnsupportedClientOutputFileNames, getBuildBundlerOptions, getClientTreeshakeConfig, getOutputFileNames, hasUserClientChunkGroups, isRscFrameworkModule, sanitizeRscChunkFileName, withBuildBundlerOptions };

package/dist/build/client-reference-groups.d.ts

@@ -0,0 +1,163 @@
+import { actionOwnerRouteEntryIds } from "./action-owner-manifest.js";
+import { Rollup } from "vite";
+//#region src/build/client-reference-groups.d.ts
+/**
+ * Client references whose estimated group cost (see
+ * {@link measureClientReferenceGroupCosts}) is larger than this many
+ * transformed source bytes keep their own lazy chunk instead of joining a route
+ * group. Grouping makes every member load with the group, so a heavy component
+ * that a route can reach but rarely renders must not be pulled into that
+ * route's startup bundle.
+ */
+export declare const CLIENT_REFERENCE_GROUP_MAX_COST_BYTES: number;
+type ClientReferenceGroupRoute = Parameters<typeof actionOwnerRouteEntryIds>[0];
+type ModuleGraphInfo = Pick<Rollup.ModuleInfo, "dynamicallyImportedIds" | "importedIds">;
+/**
+ * Map each client reference reachable from App Router route files to a
+ * signature naming the owners that reach it. A route owns its page, layouts,
+ * templates, boundaries and parallel slots, which render with it. Intercepting
+ * routes (which only render on soft navigation), global-error and
+ * global-not-found render on their own, so each is owned by its file, named by
+ * its path relative to `root`. References with the same signature are needed
+ * together, mirroring Next.js' per-route client entries. The map is in the
+ * order a depth-first walk in import order first reaches each reference from
+ * the route files in render order, which follows ES module evaluation order.
+ *
+ * References reachable from no route file (for example vinext's internal
+ * runtime references) are omitted and keep their own lazy chunk. So are
+ * references that route code reaches through a dynamic import (`next/dynamic`,
+ * `React.lazy`), directly or through the dynamically imported module's graph.
+ */
+export declare function collectClientReferenceRouteSignatures(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  clientReferenceIds: ReadonlySet<string>;
+  getModuleInfo: (id: string) => ModuleGraphInfo | null;
+  root: string;
+  routes: readonly ClientReferenceGroupRoute[];
+  sharedRoots?: readonly string[];
+}): Map<string, string>;
+export type ClientReferencePreloadPlan = {
+  /**
+   * Client references any render may use: those reached from outside route
+   * files (vinext's runtime, server actions), those of `alwaysRoots`
+   * (global-error, the root boundaries), and those no walk reaches.
+   */
+  always: string[];
+  /** The client references each route file reaches, through any import. */
+  files: string[][];
+  /** Each route pattern's files, as indices into `files`. */
+  routes: Map<string, number[]>;
+  /** The files of a render without a route, as indices into `files`. */
+  routeless: number[];
+};
+/**
+ * Plan which client references SSR loads before rendering each route. A route
+ * preloads every client reference its page, layouts, templates, boundaries and
+ * parallel slots reach, statically or through dynamic imports (a
+ * `next/dynamic` component renders on the server), plus the `always` set.
+ * Intercepting routes only render on soft navigation, which SSR never
+ * renders, so they add to no set. `entryIds` are the RSC graph's entries:
+ * walking them up to route files finds what renders outside any route.
+ */
+export declare function collectClientReferencePreloadPlan(options: {
+  alwaysRoots?: readonly string[];
+  canonicalizeModuleId?: (id: string) => string;
+  clientReferenceIds: ReadonlySet<string>;
+  entryIds: readonly string[];
+  getModuleInfo: (id: string) => ModuleGraphInfo | null;
+  routelessFiles?: readonly string[];
+  routes: readonly ClientReferenceGroupRoute[];
+}): ClientReferencePreloadPlan;
+/** Export names an importer uses from a module, or `"*"` for all of them. */
+type UsedNames = ReadonlySet<string> | "*";
+type ModuleBindings = {
+  /** Transformed source bytes, not counting import and export-list statements. */
+  bytes: number;
+  /** Static imports, with the names each one uses. */
+  imports: ReadonlyArray<{
+    id: string;
+    names: UsedNames;
+  }>;
+  /**
+   * Re-exports: `export { a as b } from`, `export * from` (`exportName` and
+   * `importName` are `"*"`), `export * as ns from` (`importName` is `"*"`), and
+   * imported bindings that the module only re-exports.
+   */
+  reexports: ReadonlyArray<{
+    id: string;
+    exportName: string;
+    importName: string;
+  }>;
+};
+type LoadedModule = {
+  code: string | null;
+  importedIds: readonly string[];
+  /**
+   * Without bindings, every static import of the module counts in full. With
+   * them, a side-effect-free module's re-exports only count for the names its
+   * importers use, as tree-shaking would keep them.
+   */
+  bindings?: ModuleBindings;
+};
+/**
+ * Read a module's static imports and re-exports for
+ * {@link measureClientReferenceGroupCosts}. Returns undefined when the code does
+ * not parse or a specifier does not resolve to one of `importedIds`.
+ */
+export declare function readClientModuleBindings(options: {
+  code: string;
+  importedIds: readonly string[];
+  resolve: (specifier: string) => Promise<string | null>;
+}): Promise<ModuleBindings | undefined>;
+/**
+ * Estimate, in transformed source bytes, how much code each client reference
+ * would add to a route group's chunk: the modules only it uses, plus the cost
+ * of every client reference it statically imports (grouping a reference pulls
+ * those along). Modules shared with other client references are not charged
+ * to any one of them, so shared libraries do not block grouping. With
+ * {@link readClientModuleBindings}, a side-effect-free module only charges the
+ * re-exports that are imported from it, so a reference that imports one icon
+ * from a barrel is not charged for the whole library.
+ *
+ * `references` maps each client reference id to its module id in the client
+ * graph. `isSideEffectFree` reports a module's package `sideEffects` flag as
+ * the bundler resolved it. Traversal stops at modules for which `isExcluded`
+ * returns true (CSS, always-loaded framework chunks, virtual modules that must
+ * not be loaded re-entrantly). A reference whose import graph cannot be fully
+ * loaded is reported as `null` so callers keep it out of groups.
+ */
+export declare function measureClientReferenceGroupCosts(options: {
+  references: ReadonlyMap<string, string>;
+  loadModule: (id: string) => Promise<LoadedModule>;
+  isExcluded: (id: string) => boolean;
+  /**
+   * Whether a module has no side effects. A side-effect-free module is not
+   * loaded until a reference uses one of its exports.
+   */
+  isSideEffectFree: (id: string) => boolean;
+}): Promise<Map<string, number | null>>;
+export type ClientReferenceGroup = {
+  /** Stable, filename-safe identifier derived from the route signature. */
+  key: string;
+  /**
+   * Member client reference ids in signature (route walk) order, which sets
+   * module evaluation and CSS order inside the group chunk.
+   */
+  referenceIds: string[];
+};
+/**
+ * Group client references that share a route signature. References without a
+ * signature, references whose cost is unknown or above `maxCostBytes`, and
+ * signatures with a single member stay ungrouped. Group keys derive from the
+ * members' `referenceKeys`, so a group keeps its chunk name when routes change
+ * but its members do not.
+ */
+export declare function planClientReferenceGroups(options: {
+  referenceIds: ReadonlySet<string>;
+  /** Stable, machine-independent key of each client reference. */
+  referenceKeys: ReadonlyMap<string, string>;
+  signatures: ReadonlyMap<string, string>;
+  costs: ReadonlyMap<string, number | null>;
+  maxCostBytes: number;
+}): ClientReferenceGroup[];
+//#endregion