vinext 1.0.0-beta.0 → 1.0.0-beta.10

package/README.md

@@ -2,6 +2,12 @@
 
 Run Next.js applications on Vite, with Cloudflare Workers as the primary deployment target.
 
+**Website:** [vinext.dev](https://vinext.dev)
+
+**Documentation:**
+
+- [Caching](docs/caching.md)
+
 > **Read the announcement:** [How we rebuilt Next.js with AI in one week](https://blog.cloudflare.com/vinext/)
 
 > **Under active development.** vinext supports substantial Next.js applications today, but it is not yet a drop-in replacement for every application or production workload. Expect compatibility gaps, especially in newer App Router features, and evaluate it against your own application before adopting it.
@@ -32,7 +38,23 @@ Run `vinext check` against an existing application before migrating. If a gap is
 
 ## Quick start
 
-vinext includes an [Agent Skill](https://agentskills.io/home) that handles migration for you. It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools. Install it, open your Next.js project, and tell the AI to migrate:
+**Use the official setup commands below.** They are the recommended way to create or migrate a vinext project because they configure dependencies, scripts, Vite, and your deployment target for you.
+
+Start a new project with `create-vinext-app`:
+
+```bash
+pnpm create vinext-app@latest my-app
+```
+
+Migrate an existing Next.js project with `vinext init`:
+
+```bash
+npx vinext init
+```
+
+### Optional: migrate with an AI agent
+
+Prefer `vinext init` for a direct, repeatable migration. If you want an AI agent to investigate compatibility issues and guide the migration, vinext also includes an optional [Agent Skill](https://agentskills.io/home). It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools:
 
 ```sh
 npx skills add cloudflare/vinext
@@ -190,7 +212,10 @@ vinext works everywhere. It natively supports Cloudflare Workers (with `npx @vin
 vinext is a Vite plugin that reimplements the public Next.js API — routing, server rendering, `next/*` module imports, the CLI — so you can run Next.js applications on Vite instead of the Next.js compiler toolchain. It can be deployed anywhere: Cloudflare Workers is the first natively supported target, with other platforms available via Nitro. Native adapters for more platforms are [planned](https://github.com/cloudflare/vinext/issues/80).
 
 **Is this a fork of Next.js?**
-No. vinext is an alternative implementation of the Next.js API surface built on Vite. It does import some Next.js types and utilities, but the core is written from scratch. The goal is not to create a competing framework or add features beyond what Next.js offers; it is to provide the same well-defined API surface on Vite's toolchain.
+No. vinext is an alternative implementation of the Next.js API surface built on Vite. The core is written from scratch. The goal is not to create a competing framework or add features beyond what Next.js offers; it is to provide the same well-defined API surface on Vite's toolchain.
+
+**Does vinext require Next.js to be installed?**
+No. vinext ships fallback declarations for the supported `next` and `next/*` APIs, so applications can run and type-check without the `next` package. If both packages are installed, vinext keeps using Next.js's authoritative types and adds only its own extensions. Compatibility features that consume Next.js internals, such as `styled-jsx`, may still require a matching Next.js installation when used.
 
 **How is this different from OpenNext?**
 [OpenNext](https://opennext.js.org/) adapts the _output_ of a standard `next build` to run on various platforms. Because it builds on Next.js's own output, it inherits broad API coverage and has been well-tested for much longer. vinext takes a different approach: it reimplements the Next.js APIs on Vite from scratch, which means faster builds and smaller bundles, but less coverage of the long tail of Next.js features. If you need a mature, well-tested way to run Next.js outside Vercel, OpenNext is the safer choice. If you want a lighter Vite-based toolchain and do not need every Next.js API, vinext may be a good fit.
@@ -326,24 +351,16 @@ Requires a custom domain (zone analytics are unavailable on `*.workers.dev`) and
 
 #### Custom Vite configuration
 
-If you need to customize the Vite config, create a `vite.config.ts`. vinext will merge its config with yours. This is required for Cloudflare Workers deployment with the App Router (RSC needs explicit plugin configuration):
+If you need to customize the Vite config, create a `vite.config.ts`. vinext will merge its config with yours. For Cloudflare Workers deployment with the App Router, configure `@cloudflare/vite-plugin` so the RSC environment runs in workerd:
 
 ```ts
 import { defineConfig } from "vite";
 import vinext from "vinext";
-import rsc from "@vitejs/plugin-rsc";
 import { cloudflare } from "@cloudflare/vite-plugin";
 
 export default defineConfig({
   plugins: [
     vinext(),
-    rsc({
-      entries: {
-        rsc: "virtual:vinext-rsc-entry",
-        ssr: "virtual:vinext-app-ssr-entry",
-        client: "virtual:vinext-app-browser-entry",
-      },
-    }),
     cloudflare({
       viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
     }),
@@ -351,6 +368,54 @@ export default defineConfig({
 });
 ```
 
+> **Do not register `@vitejs/plugin-rsc` yourself.** It is an optional peer dependency, so it must be
+> _installed_ in your project, but vinext auto-registers it whenever an `app/` directory is detected.
+> Adding an explicit `rsc()` call fails the build with `[vinext] Duplicate @vitejs/plugin-rsc detected`.
+> Pass `rsc: false` to `vinext()` only if you want to own that registration.
+
+#### Module Federation (client-side)
+
+For client-side Module Federation, configure React and React DOM as singleton shared modules in both the host and remotes:
+
+```ts
+import { federation } from "@module-federation/vite";
+import { defineConfig } from "vite";
+import vinext from "vinext";
+
+export default defineConfig({
+  plugins: [
+    federation({
+      name: "host",
+      shared: {
+        react: { singleton: true },
+        "react/": { singleton: true },
+        "react-dom": { singleton: true },
+        "react-dom/": { singleton: true },
+      },
+    }),
+    vinext(),
+  ],
+});
+```
+
+In a remote client component, use `getVinextReact()` before reading React hooks. vinext registers the host's browser React instance before application modules execute, and the first registration remains stable across remote evaluation and HMR:
+
+```tsx
+"use client";
+
+import * as React from "react";
+import { getVinextReact } from "vinext/client";
+
+const { useState } = getVinextReact(React);
+
+export function RemoteCounter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount((value) => value + 1)}>{count}</button>;
+}
+```
+
+This bridge is browser-only. It does not provide App Router Module Federation SSR or transparently replace React imports inside third-party packages; compatible React versions remain the responsibility of the Module Federation `shared` configuration.
+
 See the [examples](#live-examples) for complete working configurations.
 
 ### Other platforms (via Nitro)
@@ -456,13 +521,14 @@ These are deployed to Cloudflare Workers and updated on every push to `main`:
 | Nextra Docs            | Nextra docs site (MDX, App Router)                                                                               | [nextra-docs-template.vinext.workers.dev](https://nextra-docs-template.vinext.workers.dev)       |
 | App Router (minimal)   | Minimal App Router on Workers                                                                                    | [app-router-cloudflare.vinext.workers.dev](https://app-router-cloudflare.vinext.workers.dev)     |
 | Pages Router (minimal) | Minimal Pages Router on Workers                                                                                  | [pages-router-cloudflare.vinext.workers.dev](https://pages-router-cloudflare.vinext.workers.dev) |
+| Static export          | [Hybrid App/Pages Router site](examples/static-export) served as assets only                                     | [static-export.vinext.workers.dev](https://static-export.vinext.workers.dev)                     |
 | RealWorld API          | REST API routes example                                                                                          | [realworld-api-rest.vinext.workers.dev](https://realworld-api-rest.vinext.workers.dev)           |
-| Benchmarks Dashboard   | Build performance tracking over time (D1-backed)                                                                 | [vinext-web.vinext.workers.dev/benchmarks](https://vinext-web.vinext.workers.dev/benchmarks)     |
+| Benchmarks Dashboard   | Build performance tracking over time (D1-backed)                                                                 | [vinext.dev/benchmarks](https://vinext.dev/benchmarks)                                           |
 | App Router + Nitro     | App Router deployed via Nitro (multi-platform)                                                                   | [examples/app-router-nitro](examples/app-router-nitro)                                           |
 
 ## API coverage
 
-~94% of the Next.js 16 API surface has full or partial support. The remaining gaps are intentional stubs for deprecated features and Partial Prerendering (which Next.js 16 reworked into `"use cache"` — that directive is fully supported).
+~94% of the Next.js 16 API surface has full or partial support. The remaining gaps are intentional stubs for deprecated features, plus Partial Prerendering and Cache Components. Next.js 16 reworked PPR into `"use cache"`; vinext implements that directive for file-level and function-level caching, but full `cacheComponents` behavior is still incomplete — see [Known gaps we're working on](#known-gaps-were-working-on).
 
 > ✅ = full implementation | 🟡 = partial (runtime behavior correct, some build-time optimizations missing) | ⬜ = intentional stub/no-op
 
@@ -545,6 +611,33 @@ Every `next/*` import is shimmed to a Vite-compatible implementation.
 | `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.                                                                                                     |
+
+### React Compiler
+
+vinext auto-registers `@vitejs/plugin-react`, so the React Compiler is enabled through the same `react` option:
+
+```ts
+import { defineConfig } from "vite";
+import vinext from "vinext";
+
+export default defineConfig({
+  plugins: [vinext({ react: { compiler: true } })],
+});
+```
+
+The transform itself ships separately, so install it alongside:
+
+```bash
+npm install -D oxc-transform-react
+```
+
+This requires `@vitejs/plugin-react` 6.1.0 or newer. Older versions accept the option and drop it, so vinext fails with an actionable error instead of leaving the compiler silently disabled. The compiler runs on the client environment only.
+
+One caveat: modules whose JSX is lowered earlier in the pipeline are not memoized. Those build and behave correctly, they just miss auto memoization:
+
+- JSX in plain `.js` files, which `vinext:jsx-in-js` compiles first so the compiler can parse them at all. Rename to `.jsx` or `.tsx` to get memoization.
+- Components using `<style jsx>`, which `vinext:styled-jsx` compiles through the Next.js SWC transform before the compiler runs.
 
 ### Environment variable loading (`.env*`)
 
@@ -584,16 +677,21 @@ The cache is pluggable. The default `MemoryCacheHandler` works out of the box. S
 Instead of wiring up cache handlers imperatively from a worker entry, you can declare them in the `vinext()` plugin config. The `@vinext/cloudflare` package ships Cloudflare adapters for this:
 
 - **`kvDataAdapter()`** (`@vinext/cloudflare/cache/kv-data-adapter`) — backs the `"use cache"` data cache with a Workers KV namespace.
+- **`cdnAdapter()`** (`@vinext/cloudflare/cache/cdn-adapter`) — serves page-level ISR from the Cloudflare Workers Cache (`ctx.cache`) instead of from the origin.
+
+The two fill different slots and can be used together:
 
 ```ts
 import { defineConfig } from "vite";
 import vinext from "vinext";
+import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
 import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
 
 export default defineConfig({
   plugins: [
     vinext({
       cache: {
+        cdn: cdnAdapter(),
         data: kvDataAdapter(),
       },
     }),
@@ -609,9 +707,37 @@ The KV data adapter reads `env[binding]` at runtime, so add the matching KV name
 }
 ```
 
-`binding` defaults to `VINEXT_KV_CACHE`, so `kvDataAdapter()` with no options works as long as that's your binding name. Other options: `appPrefix` (namespace cache keys to isolate multiple apps in one KV namespace), `ttlSeconds` (default KV `expirationTtl`, default 30 days), and `tagCacheTtlMs` (in-memory tag-invalidation cache TTL, default 5s).
+`binding` defaults to `VINEXT_KV_CACHE`, so `kvDataAdapter()` with no options works as long as that's your binding name. Other options: `appPrefix` (namespace cache keys to isolate multiple apps in one KV namespace), `ttlSeconds` (default KV `expirationTtl`, default 30 days), `tagCacheTtlMs` (in-memory tag-invalidation cache TTL, default 5s), and `entryCacheTtlSeconds` (optional KV edge-cache TTL for entry reads; tag markers keep KV's default).
+
+When `cdnAdapter()` is used in a Cloudflare build, vinext emits two Worker
+entrypoints and configures Workers Cache only on the response entrypoint. The
+default entrypoint keeps caching disabled so middleware and request-time routing
+run on every request. Do not enable Workers Cache on the default entrypoint in
+your source `wrangler.jsonc`; the generated `dist/server/wrangler.json` contains
+the per-entrypoint cache settings and version metadata binding used for staged
+discovery and warming.
+
+The generated version metadata binding lets staged discovery and warming verify
+the uploaded Worker version. Pass `versionMetadataBinding` to `cdnAdapter()`
+only when the deployment needs a custom binding name.
 
-Each builder returns a plain, serializable `{ adapter, options }` descriptor — **it never touches the Workers runtime**, so nothing throws at build or dev time when bindings aren't available. The actual adapter (and its `env` binding lookup) is instantiated lazily on the first request.
+`vinext-cloudflare deploy --experimental-warm-cdn-cache` performs the two-stage
+upload and makes one final cache-fill request per admitted identity by default.
+Add `--warm-cdn-certify` only to opt into a second, header-only request that
+must prove every planned entry reusable before promotion.
+
+While the data adapter can store entries and serve HIT/STALE itself, the CDN adapter delegates serving to Cloudflare's edge: the origin renders fresh responses and tags them with `Cache-Tag`, and `revalidateTag()` / `revalidatePath()` purge the edge through `ctx.cache.purge({ tags })`. See [examples/response-store-demo](examples/response-store-demo) for the Workers Response Store adapter.
+
+The response entrypoint adds a transport-only digest of the complete stage
+identity to its Workers Cache URL. That internal key is independent of zone
+Cache Rules and prevents distinct query, representation, rewrite, or
+interception identities from colliding.
+
+Adapter declarations do not access the Workers runtime, so nothing throws at
+config-evaluation or dev time when bindings are unavailable. Builders may also
+provide platform-specific output hooks; `cdnAdapter()` uses one to configure
+the Cloudflare entrypoints after the application build. Runtime adapters (and
+their `env` binding lookups) are instantiated lazily on the first request.
 
 Registration is wired into **every router and runtime** — App Router and Pages Router, on Cloudflare Workers as well as the Node.js server (`vinext start`) and dev. It self-guards (instantiated once per isolate) and is resilient: if an adapter can't initialize on a given runtime (e.g. a KV binding doesn't exist on the Node server), vinext logs a warning and falls back to the default handler instead of failing requests.
 
@@ -622,9 +748,7 @@ vinext({
   cache: {
     data: {
       adapter: require.resolve("./my-adapter.js"),
-      options: {
-        /* … */
-      },
+      options: {/* … */},
     },
   },
 });
@@ -656,7 +780,7 @@ We measure three things:
 - **Client bundle size** — gzipped output of each build.
 - **Dev server cold start** — 10 runs, randomized execution order. Vite's dependency optimizer cache is cleared before each run.
 
-Benchmarks run on GitHub CI runners (2-core Ubuntu) on every merge to `main`. See the launch numbers in the [announcement blog post](https://blog.cloudflare.com/vinext/) and the latest results at **[vinext-web.vinext.workers.dev/benchmarks](https://vinext-web.vinext.workers.dev/benchmarks)**.
+Benchmarks run on GitHub CI runners (2-core Ubuntu) on every merge to `main`. See the launch numbers in the [announcement blog post](https://blog.cloudflare.com/vinext/) and the latest results at **[vinext.dev/benchmarks](https://vinext.dev/benchmarks)**.
 
 <details>
 <summary>Why the bundle size difference?</summary>

package/dist/build/action-owner-manifest.d.ts

@@ -0,0 +1,41 @@
+import { AppRoute } from "../routing/app-route-graph.js";
+import { Rollup } from "vite";
+import { RscPluginManager } from "@vitejs/plugin-rsc";
+//#region src/build/action-owner-manifest.d.ts
+type ActionOwnerRoute = Pick<AppRoute, "errorPath" | "errorPaths" | "forbiddenPath" | "forbiddenPaths" | "layoutErrorPaths" | "layouts" | "loadingPath" | "loadingPaths" | "notFoundPath" | "notFoundPaths" | "pagePath" | "parallelSlots" | "pattern" | "siblingIntercepts" | "templates" | "unauthorizedPath" | "unauthorizedPaths">;
+export type ActionOwnerRouteReachability = Map<string, {
+  clientReferenceImportIds: Set<string>;
+  serverReferenceIds: Set<string>;
+}>;
+type ActionOwnerModuleInfo = Pick<Rollup.ModuleInfo, "dynamicallyImportedIds" | "importedIds">;
+type ActionOwnerReferenceMaps = {
+  clientReferenceMetaMap: RscPluginManager["clientReferenceMetaMap"];
+  serverReferenceMetaMap: RscPluginManager["serverReferences"]["metaMap"];
+};
+export declare function actionOwnerRouteEntryIds(route: ActionOwnerRoute): string[];
+export declare function collectReachableActionReferences(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
+  roots: readonly string[];
+} & ActionOwnerReferenceMaps): {
+  clientReferenceImportIds: Set<string>;
+  serverReferenceIds: Set<string>;
+};
+export declare function collectRscActionReachability(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
+  routes: readonly ActionOwnerRoute[];
+  sharedRoots?: readonly string[];
+} & ActionOwnerReferenceMaps): ActionOwnerRouteReachability;
+export declare function resolveClientReferenceImportIds(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  resolveId: (id: string) => Promise<string | null>;
+  routeReachability: ActionOwnerRouteReachability;
+}): Promise<void>;
+export declare function addClientActionReachability(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
+  routeReachability: ActionOwnerRouteReachability;
+} & ActionOwnerReferenceMaps): void;
+export declare function buildActionOwnerManifest(routeReachability: ActionOwnerRouteReachability): Record<string, string[]>;
+//#endregion

package/dist/build/action-owner-manifest.js

@@ -0,0 +1,110 @@
+//#region src/build/action-owner-manifest.ts
+function actionOwnerRouteEntryIds(route) {
+	return [
+		route.pagePath,
+		...route.layouts,
+		...route.templates,
+		route.loadingPath,
+		...route.loadingPaths ?? [],
+		route.errorPath,
+		...route.layoutErrorPaths ?? [],
+		...route.errorPaths ?? [],
+		route.notFoundPath,
+		...route.notFoundPaths ?? [],
+		route.forbiddenPath,
+		...route.forbiddenPaths ?? [],
+		route.unauthorizedPath,
+		...route.unauthorizedPaths ?? [],
+		...route.parallelSlots.flatMap((slot) => [
+			slot.pagePath,
+			slot.defaultPath,
+			slot.layoutPath,
+			...slot.configLayoutPaths ?? [],
+			slot.loadingPath,
+			...slot.loadingPaths ?? [],
+			slot.errorPath,
+			slot.notFoundPath,
+			...slot.interceptingRoutes.flatMap((intercept) => [
+				intercept.pagePath,
+				...intercept.layoutPaths,
+				...intercept.loadingPaths ?? [],
+				intercept.notFoundPath
+			])
+		]),
+		...route.siblingIntercepts.flatMap((intercept) => [
+			intercept.pagePath,
+			...intercept.layoutPaths,
+			...intercept.loadingPaths ?? [],
+			intercept.notFoundPath
+		])
+	].filter((value) => typeof value === "string");
+}
+function collectReachableActionReferences(options) {
+	const canonicalizeModuleId = options.canonicalizeModuleId ?? ((id) => id);
+	const clientReferenceImportIds = /* @__PURE__ */ new Set();
+	const serverReferenceIds = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const queue = options.roots.map(canonicalizeModuleId);
+	for (let index = 0; index < queue.length; index++) {
+		const id = queue[index];
+		if (visited.has(id)) continue;
+		visited.add(id);
+		const clientReference = options.clientReferenceMetaMap[id];
+		if (clientReference) clientReferenceImportIds.add(clientReference.importId);
+		const serverReference = options.serverReferenceMetaMap.get(id);
+		if (serverReference) for (const exportName of serverReference.exportNames) serverReferenceIds.add(`${serverReference.referenceKey}#${exportName}`);
+		const info = options.getModuleInfo(id);
+		for (const importedId of [...info?.importedIds ?? [], ...info?.dynamicallyImportedIds ?? []]) if (!visited.has(importedId)) queue.push(importedId);
+	}
+	return {
+		clientReferenceImportIds,
+		serverReferenceIds
+	};
+}
+function collectRscActionReachability(options) {
+	const routeReachability = new Map(options.routes.map((route) => [route.pattern, collectReachableActionReferences({
+		canonicalizeModuleId: options.canonicalizeModuleId,
+		clientReferenceMetaMap: options.clientReferenceMetaMap,
+		getModuleInfo: options.getModuleInfo,
+		roots: actionOwnerRouteEntryIds(route),
+		serverReferenceMetaMap: options.serverReferenceMetaMap
+	})]));
+	if (options.sharedRoots?.length) routeReachability.set("*", collectReachableActionReferences({
+		canonicalizeModuleId: options.canonicalizeModuleId,
+		clientReferenceMetaMap: options.clientReferenceMetaMap,
+		getModuleInfo: options.getModuleInfo,
+		roots: options.sharedRoots,
+		serverReferenceMetaMap: options.serverReferenceMetaMap
+	}));
+	return routeReachability;
+}
+async function resolveClientReferenceImportIds(options) {
+	const canonicalizeModuleId = options.canonicalizeModuleId ?? ((id) => id);
+	for (const reachability of options.routeReachability.values()) {
+		const resolvedImportIds = /* @__PURE__ */ new Set();
+		for (const importId of reachability.clientReferenceImportIds) {
+			const resolvedId = await options.resolveId(importId) ?? importId;
+			resolvedImportIds.add(canonicalizeModuleId(resolvedId));
+		}
+		reachability.clientReferenceImportIds = resolvedImportIds;
+	}
+}
+function addClientActionReachability(options) {
+	for (const reachability of options.routeReachability.values()) {
+		const clientReachability = collectReachableActionReferences({
+			canonicalizeModuleId: options.canonicalizeModuleId,
+			clientReferenceMetaMap: options.clientReferenceMetaMap,
+			getModuleInfo: options.getModuleInfo,
+			roots: [...reachability.clientReferenceImportIds],
+			serverReferenceMetaMap: options.serverReferenceMetaMap
+		});
+		for (const actionId of clientReachability.serverReferenceIds) reachability.serverReferenceIds.add(actionId);
+	}
+}
+function buildActionOwnerManifest(routeReachability) {
+	const manifest = {};
+	for (const [pattern, reachability] of routeReachability) for (const actionId of reachability.serverReferenceIds) (manifest[actionId] ??= []).push(pattern);
+	return manifest;
+}
+//#endregion
+export { actionOwnerRouteEntryIds, addClientActionReachability, buildActionOwnerManifest, collectReachableActionReferences, collectRscActionReachability, resolveClientReferenceImportIds };

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

@@ -16,7 +16,7 @@
  * 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[];
+export declare const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS: readonly string[];
 /**
  * Ensure a `.assetsignore` in `clientDir` contains every pattern in `patterns`.
  *
@@ -27,6 +27,5 @@ declare const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS: readonly string[];
  * @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 };
+export declare function ensureAssetsIgnore(clientDir: string, patterns?: readonly string[]): boolean;
+//#endregion

package/dist/build/assets-ignore.js

@@ -1,5 +1,5 @@
+import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 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.

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

@@ -8,6 +8,5 @@ type CleanBuildOutputResult = {
   cleaned: boolean;
   outDir: string;
 };
-declare function cleanBuildOutput(options: CleanBuildOutputOptions): CleanBuildOutputResult;
-//#endregion
-export { cleanBuildOutput };
+export declare function cleanBuildOutput(options: CleanBuildOutputOptions): CleanBuildOutputResult;
+//#endregion

package/dist/build/clean-output.js

@@ -1,15 +1,12 @@
+import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
+import { isPathInsideOrEqual } from "../utils/path.js";
 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;

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

@@ -1,5 +1,4 @@
 import { UserConfig } from "vite";
-
 //#region src/build/client-build-config.d.ts
 type ClientAssetFileNameInfo = {
   readonly name?: string;
@@ -13,7 +12,7 @@ type ClientAssetFileNameInfo = {
  * 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;
+export declare function createClientAssetFileNames(assetsDir: string): (assetInfo: ClientAssetFileNameInfo) => string;
 /**
  * Create a manualChunks function for client builds.
  *
@@ -39,12 +38,12 @@ declare function createClientAssetFileNames(assetsDir: string): (assetInfo: Clie
  *   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;
-declare function createClientFileNameConfig(assetsDir: string): {
+export declare function createClientManualChunks(shimsDir: string, preserveRouteBoundaries?: boolean): (id: string) => string | undefined;
+export declare function createClientFileNameConfig(assetsDir: string): {
   entryFileNames: string;
   chunkFileNames: string;
 };
-declare function createClientCodeSplittingConfig(clientManualChunks: (id: string) => string | undefined): {
+export declare function createClientCodeSplittingConfig(clientManualChunks: (id: string) => string | undefined): {
   minSize: number;
   groups: {
     name(moduleId: string): string | null;
@@ -55,8 +54,16 @@ declare function createClientCodeSplittingConfig(clientManualChunks: (id: string
  * 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;
+export declare const RSC_FRAMEWORK_CHUNK_TEST: RegExp;
+export declare function isRscFrameworkModule(id: string): boolean;
+/**
+ * Keep virtual entry ids out of emitted RSC chunk filenames.
+ *
+ * Rolldown's entries-aware chunk names can contain the `\\0` virtual-id marker,
+ * which is not a portable module-specifier or filesystem name. Preserve every
+ * other character and remove both the printable and actual-NUL forms.
+ */
+export declare function sanitizeRscChunkFileName(name: string): string;
 /**
  * Output config that isolates React (and the RSC flight runtime) into a
  * dedicated "framework" chunk in the RSC server build. See
@@ -64,7 +71,8 @@ declare function isRscFrameworkModule(id: string): boolean;
  * modules that are only reachable through dynamic imports must stay out of the
  * eager framework chunk (issue #2073).
  */
-declare function createRscFrameworkChunkOutputConfig(): {
+export declare function createRscFrameworkChunkOutputConfig(): {
+  sanitizeFileName: typeof sanitizeRscChunkFileName;
   codeSplitting: {
     groups: {
       name: string;
@@ -81,12 +89,30 @@ declare function createRscFrameworkChunkOutputConfig(): {
  * treats node_modules as side-effect-free while preserving side effects in
  * local code.
  */
-declare function getClientTreeshakeConfig(): {
+export declare function getClientTreeshakeConfig(): {
   moduleSideEffects: "no-external";
 };
 type VinextBuildConfig = NonNullable<UserConfig["build"]>;
 type VinextBuildBundlerOptions = NonNullable<VinextBuildConfig["rolldownOptions"]>;
-declare function getBuildBundlerOptions(build: UserConfig["build"] | undefined): VinextBuildBundlerOptions | undefined;
-declare function withBuildBundlerOptions(bundlerOptions: VinextBuildBundlerOptions): Partial<VinextBuildConfig>;
-//#endregion
-export { RSC_FRAMEWORK_CHUNK_TEST, createClientAssetFileNames, createClientCodeSplittingConfig, createClientFileNameConfig, createClientManualChunks, createRscFrameworkChunkOutputConfig, getBuildBundlerOptions, getClientTreeshakeConfig, isRscFrameworkModule, withBuildBundlerOptions };
+export declare function getBuildBundlerOptions(build: UserConfig["build"] | undefined): VinextBuildBundlerOptions | undefined;
+export declare function withBuildBundlerOptions(bundlerOptions: VinextBuildBundlerOptions): Partial<VinextBuildConfig>;
+type VinextBuildOutput = Exclude<NonNullable<VinextBuildBundlerOptions["output"]>, readonly unknown[]>;
+type VinextCodeSplittingConfig = Exclude<NonNullable<VinextBuildOutput["codeSplitting"]>, boolean>;
+type ChunkFileNames = NonNullable<VinextBuildOutput["chunkFileNames"]>;
+type ChunkFileNameFunction = Exclude<ChunkFileNames, string>;
+/**
+ * Keep vinext modules partitioned by the stage entries that actually use them.
+ * Without an entry-aware catch-all, Rolldown may merge a small helper shared by
+ * request/response entries into a response-heavy chunk; importing that helper
+ * then evaluates React and renderer code on a request-stage cache hit.
+ */
+export declare function createMultiStageCodeSplittingConfig(existing: VinextBuildOutput["codeSplitting"]): VinextCodeSplittingConfig & {
+  groups: NonNullable<VinextCodeSplittingConfig["groups"]>;
+};
+/**
+ * Keep router stage chunks beside the server entry so their generated
+ * `./vinext-client-assets.js` external continues to resolve. Other chunks keep
+ * the host's existing output pattern (or vinext's server-assets default).
+ */
+export declare function createMultiStageChunkFileNames(assetsDir: string, existing: VinextBuildOutput["chunkFileNames"]): ChunkFileNameFunction;
+//#endregion