@qzsy/vinext 0.1.7

package/dist/build/assets-ignore.d.ts

@@ -0,0 +1,32 @@
+//#region src/build/assets-ignore.d.ts
+/**
+ * Build metadata that must never be served by the Cloudflare ASSETS binding.
+ *
+ * On Cloudflare Workers the ASSETS binding serves any uploaded file whose path
+ * matches the request BEFORE the Worker runs, so anything written into the
+ * client output directory (`dist/client`) is publicly fetchable unless excluded.
+ * Vite writes its build/SSR manifests under `dist/client/.vite/` (enabled for
+ * Cloudflare builds so the worker entry can compute lazy chunks), which would
+ * otherwise expose the full source-file → chunk mapping — including the paths of
+ * routes that are never linked from the UI.
+ *
+ * The Node production server already blocks `/.vite/` explicitly
+ * (see `server/static-file-cache.ts`); `.assetsignore` is the equivalent guard
+ * for the Cloudflare deployment target. wrangler matches `.assetsignore`
+ * patterns with `.gitignore` semantics (via the `ignore` package), so the bare
+ * `.vite` entry excludes the directory and everything beneath it.
+ */
+declare const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS: readonly string[];
+/**
+ * Ensure a `.assetsignore` in `clientDir` contains every pattern in `patterns`.
+ *
+ * Any pre-existing (user-authored) content is preserved verbatim and only the
+ * missing patterns are appended, so the result is idempotent across rebuilds
+ * and never clobbers a `.assetsignore` the developer wrote themselves.
+ *
+ * @returns `true` when the file was created or modified, `false` when it already
+ *          covered every requested pattern.
+ */
+declare function ensureAssetsIgnore(clientDir: string, patterns?: readonly string[]): boolean;
+//#endregion
+export { DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS, ensureAssetsIgnore };

package/dist/build/assets-ignore.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/assets-ignore.ts
+/**
+* Build metadata that must never be served by the Cloudflare ASSETS binding.
+*
+* On Cloudflare Workers the ASSETS binding serves any uploaded file whose path
+* matches the request BEFORE the Worker runs, so anything written into the
+* client output directory (`dist/client`) is publicly fetchable unless excluded.
+* Vite writes its build/SSR manifests under `dist/client/.vite/` (enabled for
+* Cloudflare builds so the worker entry can compute lazy chunks), which would
+* otherwise expose the full source-file → chunk mapping — including the paths of
+* routes that are never linked from the UI.
+*
+* The Node production server already blocks `/.vite/` explicitly
+* (see `server/static-file-cache.ts`); `.assetsignore` is the equivalent guard
+* for the Cloudflare deployment target. wrangler matches `.assetsignore`
+* patterns with `.gitignore` semantics (via the `ignore` package), so the bare
+* `.vite` entry excludes the directory and everything beneath it.
+*/
+const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS = [".vite"];
+/** wrangler reads asset-exclusion patterns from this file in the assets dir. */
+const ASSETS_IGNORE_FILENAME = ".assetsignore";
+const GENERATED_HEADER = "# Keep build metadata out of the deployed asset bundle (generated by vinext)";
+/**
+* Ensure a `.assetsignore` in `clientDir` contains every pattern in `patterns`.
+*
+* Any pre-existing (user-authored) content is preserved verbatim and only the
+* missing patterns are appended, so the result is idempotent across rebuilds
+* and never clobbers a `.assetsignore` the developer wrote themselves.
+*
+* @returns `true` when the file was created or modified, `false` when it already
+*          covered every requested pattern.
+*/
+function ensureAssetsIgnore(clientDir, patterns = DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS) {
+	const assetsIgnorePath = path.join(clientDir, ASSETS_IGNORE_FILENAME);
+	const existing = fs.existsSync(assetsIgnorePath) ? fs.readFileSync(assetsIgnorePath, "utf-8") : null;
+	const present = new Set((existing ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+	const missing = patterns.filter((pattern) => !present.has(pattern));
+	if (missing.length === 0) return false;
+	const lines = existing && existing.trim().length > 0 ? [existing.replace(/\s*$/, "")] : [GENERATED_HEADER];
+	lines.push(...missing, "");
+	fs.mkdirSync(clientDir, { recursive: true });
+	fs.writeFileSync(assetsIgnorePath, lines.join("\n"));
+	return true;
+}
+//#endregion
+export { DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS, ensureAssetsIgnore };

package/dist/build/clean-output.d.ts

@@ -0,0 +1,13 @@
+//#region src/build/clean-output.d.ts
+type CleanBuildOutputOptions = {
+  root: string;
+  outDir?: string;
+  emptyOutDir?: boolean;
+};
+type CleanBuildOutputResult = {
+  cleaned: boolean;
+  outDir: string;
+};
+declare function cleanBuildOutput(options: CleanBuildOutputOptions): CleanBuildOutputResult;
+//#endregion
+export { cleanBuildOutput };

package/dist/build/clean-output.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/clean-output.ts
+function resolveOutDir(root, outDir) {
+	const resolvedRoot = path.resolve(root);
+	if (!outDir) return path.join(resolvedRoot, "dist");
+	return path.isAbsolute(outDir) ? outDir : path.resolve(resolvedRoot, outDir);
+}
+function isPathInsideOrEqual(parent, child) {
+	const relative = path.relative(parent, child);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function shouldCleanBuildOutput(options) {
+	if (options.emptyOutDir === false) return false;
+	if (options.emptyOutDir === true) return true;
+	return isPathInsideOrEqual(path.resolve(options.root), resolveOutDir(options.root, options.outDir));
+}
+function cleanBuildOutput(options) {
+	const outDir = resolveOutDir(options.root, options.outDir);
+	if (!shouldCleanBuildOutput(options)) return {
+		cleaned: false,
+		outDir
+	};
+	fs.rmSync(outDir, {
+		recursive: true,
+		force: true
+	});
+	return {
+		cleaned: true,
+		outDir
+	};
+}
+//#endregion
+export { cleanBuildOutput };

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

@@ -0,0 +1,171 @@
+import { UserConfig } from "vite";
+
+//#region src/build/client-build-config.d.ts
+type ClientAssetFileNameInfo = {
+  readonly name?: string;
+  readonly names?: readonly string[];
+  readonly originalFileName?: string;
+  readonly originalFileNames?: readonly string[];
+};
+type RscFrameworkModuleInfo = {
+  importers: string[];
+  isEntry: boolean;
+};
+type RscFrameworkManualChunksMeta = {
+  getModuleInfo(id: string): RscFrameworkModuleInfo | null;
+};
+/**
+ * Routes client assets into Next-compatible subtrees: `.css` sources go to
+ * `<assetsDir>/css/`, everything else to `<assetsDir>/media/`. Returned as a
+ * function so it can inspect every source-name candidate Rolldown records for
+ * an asset (a single output asset can carry several `originalFileNames`).
+ */
+declare function createClientAssetFileNames(assetsDir: string): (assetInfo: ClientAssetFileNameInfo) => string;
+/**
+ * Create a manualChunks function for client builds.
+ *
+ * Splits the client bundle into:
+ * - "framework" — React, ReactDOM, and scheduler (loaded on every page)
+ * - "vinext"    — shared vinext runtime shims
+ *
+ * Route-owned client shims and all other vendor code are left to the bundler's
+ * graph-based chunking so they stay behind their client-reference boundaries.
+ *
+ * Why not split every npm package into its own chunk?
+ * - Per-package splitting (`vendor-X`) creates 50-200+ chunks for a
+ *   typical app, far exceeding the ~25-request sweet spot for HTTP/2.
+ * - gzip/brotli compress small files poorly — each file restarts with
+ *   an empty dictionary, losing ~5-15% total compressed size vs fewer
+ *   larger chunks (Khan Academy measured +2.5% wire size with 10x
+ *   more files containing less raw code).
+ * - ES module evaluation has per-module overhead that compounds on
+ *   mobile devices.
+ * - No major Vite-based framework (Remix, SvelteKit, Astro, TanStack)
+ *   uses per-package splitting. Next.js only isolates packages >160KB.
+ * - Rollup's graph-based splitting already handles the common case
+ *   well: shared dependencies between routes get their own chunks,
+ *   and route-specific code stays in route chunks.
+ */
+declare function createClientManualChunks(shimsDir: string, preserveRouteBoundaries?: boolean): (id: string) => string | undefined;
+/**
+ * Rollup output config with manualChunks for client code-splitting.
+ * Used by both CLI builds and multi-environment builds.
+ *
+ * experimentalMinChunkSize merges tiny shared chunks (< 10KB) back into
+ * their importers. This reduces HTTP request count and improves gzip
+ * compression efficiency — small files restart the compression dictionary,
+ * adding ~5-15% wire overhead vs fewer larger chunks.
+ */
+declare function createClientFileNameConfig(assetsDir: string): {
+  entryFileNames: string;
+  chunkFileNames: string;
+};
+declare function createClientOutputConfig(clientManualChunks: (id: string) => string | undefined, assetsDir: string): {
+  assetFileNames: (assetInfo: ClientAssetFileNameInfo) => string;
+  manualChunks: (id: string) => string | undefined;
+  experimentalMinChunkSize: number;
+  entryFileNames: string;
+  chunkFileNames: string;
+};
+declare function createClientCodeSplittingConfig(clientManualChunks: (id: string) => string | undefined): {
+  minSize: number;
+  groups: {
+    name(moduleId: string): string | null;
+  }[];
+};
+/**
+ * Regex matching any {@link FRAMEWORK_PACKAGES} package inside `node_modules`.
+ * Derived from the package list so the regex and {@link isRscFrameworkModule}
+ * predicate can't drift.
+ */
+declare const RSC_FRAMEWORK_CHUNK_TEST: RegExp;
+declare function isRscFrameworkModule(id: string): boolean;
+/**
+ * Output config that isolates React (and the RSC flight runtime) into a
+ * dedicated "framework" chunk in the RSC server build. Returns the bundler-
+ * appropriate shape: rolldown's `codeSplitting` for Vite 8+, Rollup's
+ * `manualChunks` for Vite 7. See {@link RSC_FRAMEWORK_CHUNK_TEST} for the
+ * motivation (issue #1549). Framework modules that are only reachable through
+ * dynamic imports must stay out of the eager framework chunk (issue #2073).
+ */
+declare function createRscFrameworkChunkOutputConfig(viteMajorVersion: number): {
+  codeSplitting: {
+    groups: {
+      name: string;
+      test: RegExp;
+      entriesAware: boolean;
+    }[];
+  };
+  manualChunks?: undefined;
+} | {
+  manualChunks(id: string, meta: RscFrameworkManualChunksMeta): string | undefined;
+  codeSplitting?: undefined;
+};
+/**
+ * Rollup treeshake configuration for production client builds.
+ *
+ * Uses the 'recommended' preset as a safe base, then overrides
+ * moduleSideEffects to strip unused re-exports from npm packages.
+ *
+ * The 'no-external' value for moduleSideEffects means:
+ * - Local project modules: preserve side effects (CSS imports, polyfills)
+ * - node_modules packages: treat as side-effect-free unless exports are used
+ *
+ * This is the single highest-impact optimization for large barrel-exporting
+ * libraries like mermaid, @mui/material, lucide-react, etc. These libraries
+ * re-export hundreds of sub-modules through barrel files. Without this,
+ * Rollup preserves every sub-module even when only a few exports are consumed.
+ *
+ * Why 'no-external' instead of false (global side-effect-free)?
+ * - User code may rely on import-time side effects (e.g., `import './global.css'`)
+ * - 'no-external' is safe for app code while still enabling aggressive DCE for deps
+ *
+ * Why not the 'smallest' preset?
+ * - 'smallest' also sets propertyReadSideEffects: false and
+ *   tryCatchDeoptimization: false, which can break specific libraries
+ *   that rely on property access side effects or try/catch for feature detection
+ * - 'recommended' + 'no-external' gives most of the benefit with less risk
+ *
+ * @deprecated Use getClientTreeshakeConfigForVite(viteMajorVersion) instead
+ * for Vite version compatibility. Kept for backward compatibility.
+ */
+declare const clientTreeshakeConfig: {
+  preset: "recommended";
+  moduleSideEffects: "no-external";
+};
+/**
+ * Returns treeshake configuration appropriate for the Vite version.
+ *
+ * Rollup (Vite 7) supports presets like "recommended" which set multiple
+ * treeshake options at once. Rolldown (Vite 8+) doesn't support presets,
+ * so we only return moduleSideEffects for Vite 8+.
+ *
+ * The Rollup "recommended" preset sets:
+ * - annotations: true (Rolldown default is also true)
+ * - manualPureFunctions: [] (Rolldown default is also [])
+ * - propertyReadSideEffects: true (Rolldown equivalent is 'always', the default)
+ * - unknownGlobalSideEffects: false (Rolldown default is true — this is a known acceptable
+ *   divergence. Slightly less aggressive DCE on unknown globals, acceptable for client bundles)
+ * - correctVarValueBeforeDeclaration and tryCatchDeoptimization (Rolldown handles these differently)
+ *
+ * The key optimization is moduleSideEffects: "no-external", which is supported
+ * by both bundlers and provides the DCE benefits for barrel-exporting libraries.
+ * It treats node_modules as side-effect-free (enabling aggressive DCE) while
+ * preserving side effects in local code.
+ */
+declare function getClientTreeshakeConfigForVite(viteMajorVersion: number): {
+  moduleSideEffects: "no-external";
+  preset?: undefined;
+} | {
+  preset: "recommended";
+  moduleSideEffects: "no-external";
+};
+type VinextBuildConfig = NonNullable<UserConfig["build"]>;
+type VinextBuildBundlerOptions = NonNullable<VinextBuildConfig["rolldownOptions"]>;
+type VinextBuildConfigWithLegacy = VinextBuildConfig & {
+  rollupOptions?: VinextBuildBundlerOptions;
+};
+declare function getBuildBundlerOptions(build: UserConfig["build"] | undefined): VinextBuildBundlerOptions | undefined;
+declare function withBuildBundlerOptions(viteMajorVersion: number, bundlerOptions: VinextBuildBundlerOptions): Partial<VinextBuildConfigWithLegacy>;
+//#endregion
+export { RSC_FRAMEWORK_CHUNK_TEST, clientTreeshakeConfig, createClientAssetFileNames, createClientCodeSplittingConfig, createClientFileNameConfig, createClientManualChunks, createClientOutputConfig, createRscFrameworkChunkOutputConfig, getBuildBundlerOptions, getClientTreeshakeConfigForVite, isRscFrameworkModule, withBuildBundlerOptions };

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

@@ -0,0 +1,270 @@
+//#region src/build/client-build-config.ts
+const ROUTE_OWNED_CLIENT_SHIMS = new Set([
+	"compat-router",
+	"dynamic",
+	"dynamic-preload-chunks",
+	"form",
+	"image",
+	"layout-segment-context",
+	"legacy-image",
+	"link",
+	"offline",
+	"router",
+	"script",
+	"web-vitals"
+]);
+const NEXT_CLIENT_CSS_ASSET_FILE_NAMES = "css/[name].[hash:8][extname]";
+const NEXT_CLIENT_STATIC_MEDIA_FILE_NAMES = "media/[name].[hash:8][extname]";
+function joinAssetFileNamePattern(assetsDir, pattern) {
+	let end = assetsDir.length;
+	while (end > 0 && assetsDir[end - 1] === "/") end -= 1;
+	const normalized = assetsDir.slice(0, end);
+	return normalized ? `${normalized}/${pattern}` : pattern;
+}
+/**
+* Routes client assets into Next-compatible subtrees: `.css` sources go to
+* `<assetsDir>/css/`, everything else to `<assetsDir>/media/`. Returned as a
+* function so it can inspect every source-name candidate Rolldown records for
+* an asset (a single output asset can carry several `originalFileNames`).
+*/
+function createClientAssetFileNames(assetsDir) {
+	const cssAssetFileNames = joinAssetFileNamePattern(assetsDir, NEXT_CLIENT_CSS_ASSET_FILE_NAMES);
+	const mediaAssetFileNames = joinAssetFileNamePattern(assetsDir, NEXT_CLIENT_STATIC_MEDIA_FILE_NAMES);
+	return function getClientAssetFileNames(assetInfo) {
+		return [
+			...assetInfo.names ?? [],
+			assetInfo.name,
+			...assetInfo.originalFileNames ?? [],
+			assetInfo.originalFileName
+		].some((name) => name?.toLowerCase().endsWith(".css")) ? cssAssetFileNames : mediaAssetFileNames;
+	};
+}
+/**
+* Extract the npm package name from a module ID (file path).
+* Returns null if not in node_modules.
+*
+* Handles scoped packages (@org/pkg) and pnpm-style paths
+* (node_modules/.pnpm/pkg@ver/node_modules/pkg).
+*/
+function getPackageName(id) {
+	const normalizedId = id.replaceAll("\\", "/");
+	const nmIdx = normalizedId.lastIndexOf("node_modules/");
+	if (nmIdx === -1) return null;
+	const rest = normalizedId.slice(nmIdx + 13);
+	if (rest.startsWith("@")) {
+		const parts = rest.split("/");
+		return parts.length >= 2 ? parts[0] + "/" + parts[1] : null;
+	}
+	return rest.split("/")[0] || null;
+}
+/**
+* Create a manualChunks function for client builds.
+*
+* Splits the client bundle into:
+* - "framework" — React, ReactDOM, and scheduler (loaded on every page)
+* - "vinext"    — shared vinext runtime shims
+*
+* Route-owned client shims and all other vendor code are left to the bundler's
+* graph-based chunking so they stay behind their client-reference boundaries.
+*
+* Why not split every npm package into its own chunk?
+* - Per-package splitting (`vendor-X`) creates 50-200+ chunks for a
+*   typical app, far exceeding the ~25-request sweet spot for HTTP/2.
+* - gzip/brotli compress small files poorly — each file restarts with
+*   an empty dictionary, losing ~5-15% total compressed size vs fewer
+*   larger chunks (Khan Academy measured +2.5% wire size with 10x
+*   more files containing less raw code).
+* - ES module evaluation has per-module overhead that compounds on
+*   mobile devices.
+* - No major Vite-based framework (Remix, SvelteKit, Astro, TanStack)
+*   uses per-package splitting. Next.js only isolates packages >160KB.
+* - Rollup's graph-based splitting already handles the common case
+*   well: shared dependencies between routes get their own chunks,
+*   and route-specific code stays in route chunks.
+*/
+function createClientManualChunks(shimsDir, preserveRouteBoundaries = false) {
+	return function clientManualChunks(id) {
+		if (id.includes("node_modules")) {
+			const pkg = getPackageName(id);
+			if (!pkg) return void 0;
+			if (pkg === "react" || pkg === "react-dom" || pkg === "scheduler") return "framework";
+			return;
+		}
+		if (id.startsWith(shimsDir)) {
+			if (preserveRouteBoundaries) {
+				const relativeId = id.slice(shimsDir.length).split("?", 1)[0] ?? "";
+				const extensionIndex = relativeId.lastIndexOf(".");
+				const shimName = extensionIndex === -1 ? relativeId : relativeId.slice(0, extensionIndex);
+				if (ROUTE_OWNED_CLIENT_SHIMS.has(shimName)) return void 0;
+			}
+			return "vinext";
+		}
+	};
+}
+/**
+* Rollup output config with manualChunks for client code-splitting.
+* Used by both CLI builds and multi-environment builds.
+*
+* experimentalMinChunkSize merges tiny shared chunks (< 10KB) back into
+* their importers. This reduces HTTP request count and improves gzip
+* compression efficiency — small files restart the compression dictionary,
+* adding ~5-15% wire overhead vs fewer larger chunks.
+*/
+function createClientFileNameConfig(assetsDir) {
+	const chunksDir = `${assetsDir}/chunks`;
+	return {
+		entryFileNames: `${chunksDir}/[name]-[hash].js`,
+		chunkFileNames: `${chunksDir}/[name]-[hash].js`
+	};
+}
+function createClientOutputConfig(clientManualChunks, assetsDir) {
+	return {
+		...createClientFileNameConfig(assetsDir),
+		assetFileNames: createClientAssetFileNames(assetsDir),
+		manualChunks: clientManualChunks,
+		experimentalMinChunkSize: 1e4
+	};
+}
+function createClientCodeSplittingConfig(clientManualChunks) {
+	return {
+		minSize: 1e4,
+		groups: [{ name(moduleId) {
+			return clientManualChunks(moduleId) ?? null;
+		} }]
+	};
+}
+/**
+* Matches React framework packages (and the RSC flight runtime) inside
+* `node_modules`. Used to split them into a dedicated "framework" chunk in the
+* RSC server build.
+*
+* Why the RSC build needs this: without an explicit framework chunk, the
+* bundler colocates React into whichever chunk first reaches it — typically the
+* RSC entry chunk, which also carries the root layout's CSS. Modules that only
+* import React for runtime helpers (notably `app/global-not-found.tsx`, which
+* replaces the root layout for route-miss 404s) then import that entry chunk
+* and inherit the root layout's CSS in their `serverResources` metadata. The
+* 404 document ends up linking the layout's stylesheet last, so the layout's
+* rules win the cascade over global-not-found's — the bug tracked in
+* https://github.com/cloudflare/vinext/issues/1549.
+*
+* Splitting React into its own (CSS-free) chunk means global-not-found imports
+* the framework chunk instead of the layout-bearing entry chunk, so it no
+* longer inherits the root layout's CSS. The match list mirrors the client
+* build's `framework` chunk, plus `react-server-dom-webpack` for the RSC flight
+* runtime that the server environment bundles.
+*
+* Uses `[\\/]` rather than `/` for the path separator so it matches on Windows
+* too, per the rolldown `codeSplitting` docs.
+*/
+const FRAMEWORK_PACKAGES = [
+	"react",
+	"react-dom",
+	"scheduler",
+	"react-server-dom-webpack"
+];
+/**
+* Regex matching any {@link FRAMEWORK_PACKAGES} package inside `node_modules`.
+* Derived from the package list so the regex and {@link isRscFrameworkModule}
+* predicate can't drift.
+*/
+const RSC_FRAMEWORK_CHUNK_TEST = new RegExp(`[\\\\/]node_modules[\\\\/](${FRAMEWORK_PACKAGES.join("|")})[\\\\/]`);
+function isRscFrameworkModule(id) {
+	if (!id.includes("node_modules")) return false;
+	const pkg = getPackageName(id);
+	return pkg !== null && FRAMEWORK_PACKAGES.includes(pkg);
+}
+function isStaticallyReachableFromEntry(id, meta, visited = /* @__PURE__ */ new Set()) {
+	if (visited.has(id)) return false;
+	visited.add(id);
+	const moduleInfo = meta.getModuleInfo(id);
+	if (!moduleInfo) return false;
+	if (moduleInfo.isEntry) return true;
+	return moduleInfo.importers.some((importer) => isStaticallyReachableFromEntry(importer, meta, visited));
+}
+/**
+* Output config that isolates React (and the RSC flight runtime) into a
+* dedicated "framework" chunk in the RSC server build. Returns the bundler-
+* appropriate shape: rolldown's `codeSplitting` for Vite 8+, Rollup's
+* `manualChunks` for Vite 7. See {@link RSC_FRAMEWORK_CHUNK_TEST} for the
+* motivation (issue #1549). Framework modules that are only reachable through
+* dynamic imports must stay out of the eager framework chunk (issue #2073).
+*/
+function createRscFrameworkChunkOutputConfig(viteMajorVersion) {
+	if (viteMajorVersion >= 8) return { codeSplitting: { groups: [{
+		name: "framework",
+		test: RSC_FRAMEWORK_CHUNK_TEST,
+		entriesAware: true
+	}] } };
+	return { manualChunks(id, meta) {
+		return isRscFrameworkModule(id) && isStaticallyReachableFromEntry(id, meta) ? "framework" : void 0;
+	} };
+}
+/**
+* Rollup treeshake configuration for production client builds.
+*
+* Uses the 'recommended' preset as a safe base, then overrides
+* moduleSideEffects to strip unused re-exports from npm packages.
+*
+* The 'no-external' value for moduleSideEffects means:
+* - Local project modules: preserve side effects (CSS imports, polyfills)
+* - node_modules packages: treat as side-effect-free unless exports are used
+*
+* This is the single highest-impact optimization for large barrel-exporting
+* libraries like mermaid, @mui/material, lucide-react, etc. These libraries
+* re-export hundreds of sub-modules through barrel files. Without this,
+* Rollup preserves every sub-module even when only a few exports are consumed.
+*
+* Why 'no-external' instead of false (global side-effect-free)?
+* - User code may rely on import-time side effects (e.g., `import './global.css'`)
+* - 'no-external' is safe for app code while still enabling aggressive DCE for deps
+*
+* Why not the 'smallest' preset?
+* - 'smallest' also sets propertyReadSideEffects: false and
+*   tryCatchDeoptimization: false, which can break specific libraries
+*   that rely on property access side effects or try/catch for feature detection
+* - 'recommended' + 'no-external' gives most of the benefit with less risk
+*
+* @deprecated Use getClientTreeshakeConfigForVite(viteMajorVersion) instead
+* for Vite version compatibility. Kept for backward compatibility.
+*/
+const clientTreeshakeConfig = {
+	preset: "recommended",
+	moduleSideEffects: "no-external"
+};
+/**
+* Returns treeshake configuration appropriate for the Vite version.
+*
+* Rollup (Vite 7) supports presets like "recommended" which set multiple
+* treeshake options at once. Rolldown (Vite 8+) doesn't support presets,
+* so we only return moduleSideEffects for Vite 8+.
+*
+* The Rollup "recommended" preset sets:
+* - annotations: true (Rolldown default is also true)
+* - manualPureFunctions: [] (Rolldown default is also [])
+* - propertyReadSideEffects: true (Rolldown equivalent is 'always', the default)
+* - unknownGlobalSideEffects: false (Rolldown default is true — this is a known acceptable
+*   divergence. Slightly less aggressive DCE on unknown globals, acceptable for client bundles)
+* - correctVarValueBeforeDeclaration and tryCatchDeoptimization (Rolldown handles these differently)
+*
+* The key optimization is moduleSideEffects: "no-external", which is supported
+* by both bundlers and provides the DCE benefits for barrel-exporting libraries.
+* It treats node_modules as side-effect-free (enabling aggressive DCE) while
+* preserving side effects in local code.
+*/
+function getClientTreeshakeConfigForVite(viteMajorVersion) {
+	if (viteMajorVersion >= 8) return { moduleSideEffects: "no-external" };
+	return {
+		preset: "recommended",
+		moduleSideEffects: "no-external"
+	};
+}
+function getBuildBundlerOptions(build) {
+	const buildConfig = build;
+	return buildConfig?.rolldownOptions ?? buildConfig?.rollupOptions;
+}
+function withBuildBundlerOptions(viteMajorVersion, bundlerOptions) {
+	return viteMajorVersion >= 8 ? { rolldownOptions: bundlerOptions } : { rollupOptions: bundlerOptions };
+}
+//#endregion
+export { RSC_FRAMEWORK_CHUNK_TEST, clientTreeshakeConfig, createClientAssetFileNames, createClientCodeSplittingConfig, createClientFileNameConfig, createClientManualChunks, createClientOutputConfig, createRscFrameworkChunkOutputConfig, getBuildBundlerOptions, getClientTreeshakeConfigForVite, isRscFrameworkModule, withBuildBundlerOptions };

package/dist/build/css-url-assets.d.ts

@@ -0,0 +1,29 @@
+import { Rolldown } from "vite";
+
+//#region src/build/css-url-assets.d.ts
+type BundleAsset = Rolldown.OutputAsset;
+type CssUrlAssetBundle = Rolldown.OutputBundle;
+type EmitRestoredCssUrlAsset = (asset: {
+  fileName: string;
+  source: BundleAsset["source"];
+}) => void;
+/**
+ * Append the private provenance marker to each relative asset `url()` in a CSS
+ * source. Idempotent and side-effect free (only adds a query param), so it is
+ * safe to run on every build-environment stylesheet, vendored CSS included.
+ */
+declare function markCssUrlAssetReferences(code: string, id: string): string | null;
+/**
+ * Mutates emitted CSS assets in place so byte-identical `url()` dependencies
+ * keep their distinct Next-compatible filenames. Sibling files are produced via
+ * `emitRestoredAsset` (which must call `this.emitFile({ type: "asset", fileName,
+ * source })` — the explicit `fileName` opts out of Rolldown's content dedupe).
+ *
+ * Expects CSS to have been marked by `markCssUrlAssetReferences()` first. The
+ * marker is stripped from all final output here. CSS that Vite inlined into a JS
+ * chunk (`cssCodeSplit: false` / `?inline`) already has final URLs, so chunk
+ * code only has the leaked marker stripped — no sibling files are emitted.
+ */
+declare function restoreDedupedCssAssetReferences(bundle: CssUrlAssetBundle, emitRestoredAsset: EmitRestoredCssUrlAsset): void;
+//#endregion
+export { markCssUrlAssetReferences, restoreDedupedCssAssetReferences };