@rsc-kit/core 0.18.1 → 0.20.0

package/dist/vite.js

@@ -30,8 +30,9 @@ import { serverImportsOfClientPackages } from "./clientImports.js";
 import { automaticSitemap, METADATA_ROUTES, ROOT_FILES, rootFileType, } from "./metadataRoutes.js";
 import { ownHosts } from "./hostRouting.js";
 import { unrollBarrelImports } from "./barrelImports.js";
-import { serverRendererMessage, SERVER_RENDERER, ssrProxyModule, UseSsrError, } from "./useSsr.js";
+import { serverRendererMessage, SERVER_RENDERER, ssrProxyModule, UseSsrError, withoutSsrDirective } from "./useSsr.js";
 import { httpHostCalls } from "./hostCalls.js";
+import { clientPackages, importsServerRenderer, packageDir as installedPackageDir, packageEntryInGraph } from "./clientPackages.js";
 // Resolved once per rscKit() call. One build runs in one process, so these are
 // module state rather than threaded through every helper.
 let projectRoot;
@@ -52,6 +53,12 @@ const RUNTIME_BUILTINS = ["bun", /^bun:/];
  * Next keeps the same list under serverExternalPackages, for the same reason.
  * `rscKit({ serverExternalPackages })` adds to it.
  */
+/**
+ * Side-effect polyfills a dependency checks for at module evaluation, which
+ * the generated entry imports before anything else when the project has
+ * them. Bundler chunking does not keep an external import's place.
+ */
+const FIRST_POLYFILLS = ["reflect-metadata"];
 const DEFAULT_SERVER_EXTERNALS = [
     "sharp",
     "canvas",
@@ -78,6 +85,13 @@ const DEFAULT_SERVER_EXTERNALS = [
     "oslo",
     "@resvg/resvg-js",
     "@napi-rs/canvas",
+    // Not native: a polyfill that must run before anything reads Reflect.getMetadata.
+    // tsyringe, typeorm and inversify check for it at module evaluation, and a
+    // bundler that splits them into their own chunk hoists that chunk's evaluation
+    // above the polyfill's - so the check fails in a bundle that has the polyfill
+    // in it. External, the import statement stays where the source put it, and
+    // Node runs it first.
+    "reflect-metadata",
 ];
 /** A package name as a rollup external: the package and every subpath of it. */
 function externalPackage(name) {
@@ -156,6 +170,8 @@ let siteHosts = [];
 let hostsOption = [];
 let barrelImports = true;
 let identify = true;
+/** Resolved from RscKitOptions.openapi; null when off. */
+let openapi = null;
 let foundAssets = {
     favicon: null,
     icons: [],
@@ -218,6 +234,12 @@ function fileHostActions(root) {
         return {};
     try {
         const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        // An empty list is an empty map. PHP's json_encode writes an empty
+        // array as [] whatever it was declared as, so a backend with no
+        // actions yet wrote exactly that - and the first `dev` of a fresh
+        // install refused to start over a file that said, correctly, "none".
+        if (Array.isArray(parsed) && parsed.length === 0)
+            return {};
         if (parsed === null ||
             typeof parsed !== "object" ||
             Array.isArray(parsed)) {
@@ -243,16 +265,23 @@ function fileHostActions(root) {
  * two cannot drift.
  */
 function aliasEntries() {
+    const entries = [
+        // A library written for Next reads the request through next/headers -
+        // Vercel's flags SDK does, through `flags/next` - and headers() and
+        // cookies() here have the same names and shapes, with one object per
+        // request, which is what its per-request dedupe keys on. Answered by
+        // this package, so such a library runs unchanged and without Next.
+        { find: /^next\/headers$/, replacement: join(packageDir, "request") },
+    ];
     if (!packageAlias)
-        return [];
+        return entries;
     if (existsSync(join(projectRoot, "node_modules", packageAlias)))
-        return [];
-    return [
-        {
-            find: new RegExp("^" + packageAlias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "/(.*)$"),
-            replacement: join(packageDir, "js") + "/$1",
-        },
-    ];
+        return entries;
+    entries.push({
+        find: new RegExp("^" + packageAlias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "/(.*)$"),
+        replacement: join(packageDir, "js") + "/$1",
+    });
+    return entries;
 }
 function resolvePaths(options) {
     projectRoot = resolve(options.projectRoot || process.env.RSC_PROJECT_ROOT || process.cwd());
@@ -321,6 +350,12 @@ function resolvePaths(options) {
     hostsOption = options.hosts ?? [];
     barrelImports = options.barrelImports !== false;
     identify = options.identify !== false;
+    openapi = options.openapi
+        ? (() => {
+            const { path, ...document } = typeof options.openapi === "object" ? options.openapi : {};
+            return { path: path || "/openapi.json", document };
+        })()
+        : null;
     inlineStylesheets = options.inlineStylesheets ?? "auto";
     maxActionBody = options.maxActionBody;
     // One place, and it is the file. A plugin option as well would be the same
@@ -550,10 +585,16 @@ function routeManifest() {
         },
         routes,
         intercepts,
-        apis: [...apiRoutes.values()].map(({ name, methods, generated }) => ({
+        apis: [...apiRoutes.values()].map(({ name, methods, generated, absPath }) => ({
             name,
             segments: urlSegments(name),
             methods,
+            // The OpenAPI document is synthesised from nothing on disk.
+            source: generated
+                ? generated.file
+                    ? relative(sourceDir, generated.file).replace(/\\/g, "/")
+                    : undefined
+                : relative(sourceDir, absPath).replace(/\\/g, "/"),
             // A synthesised robots.txt or sitemap.xml runs no guard: it exists to be
             // read by anyone, and a guard on the root would 401 the crawler.
             middleware: generated ? [] : ancestors(name, "middleware"),
@@ -765,7 +806,32 @@ self.addEventListener('install', (event) => {
       // it is served by the host out of the prerendered directory, which this
       // worker cannot see. Added here so it is in the cache before it is
       // needed, which is the only moment it cannot be fetched.
-      .then((cache) => cache.addAll(OFFLINE_URL ? [...PRECACHE, OFFLINE_URL] : PRECACHE))
+      .then((cache) => cache.addAll(OFFLINE_URL ? [...PRECACHE, OFFLINE_URL] : PRECACHE).then(() => cache))
+      // And the payload each precached page boots from. A document alone is
+      // markup that never hydrates: the client fetches its payload on boot,
+      // and a precached / rendered offline and stayed inert because that
+      // request had nothing cached to answer it.
+      .then((cache) =>
+        Promise.all(
+          PRECACHE.filter((url) => !/\\.[a-z0-9]+$/i.test(url))
+            .concat(OFFLINE_URL ? [OFFLINE_URL] : [])
+            .map((url) => {
+              const warm = new Request(url, { headers: { 'X-RSC': '1' } })
+
+              return fetch(warm)
+                .then((payload) => {
+                  if (mayStore(payload)) return cache.put(keyFor(warm), payload)
+
+                  // Said, not swallowed: a page whose payload cannot be kept
+                  // is one that will render offline and never hydrate, and
+                  // the reason - a no-store from a guard above it, usually -
+                  // is only visible here.
+                  console.warn('[rsc-kit] offline: the payload for ' + url + ' was not stored (' + (payload.headers.get('Cache-Control') || payload.status) + '), so it will not hydrate offline')
+                })
+                .catch(() => {})
+            }),
+        ),
+      )
       .then(() => self.skipWaiting()),
   )
 })
@@ -774,9 +840,16 @@ self.addEventListener('activate', (event) => {
   event.waitUntil(
     caches
       .keys()
-      .then((keys) => Promise.all(keys.filter((k) => k.startsWith('rsc-kit-') && k !== CACHE).map((k) => caches.delete(k))))
-      .then(() => self.clients.claim())
-      .then(() => tellTheOpenPages()),
+      .then((keys) => {
+        const older = keys.filter((k) => k.startsWith('rsc-kit-') && k !== CACHE)
+
+        return Promise.all(older.map((k) => caches.delete(k))).then(() => older.length > 0)
+      })
+      .then((swept) => self.clients.claim().then(() => swept))
+      // Only when something older was swept. The first worker a visitor ever
+      // gets activates too, and told them "a new version is ready" on their
+      // second page - there was no previous version to be new against.
+      .then((swept) => (swept ? tellTheOpenPages() : undefined)),
   )
 })
 
@@ -821,6 +894,37 @@ const keyFor = (request) => {
   return new Request(url, { headers: request.headers })
 }
 
+// Nothing cached for a request and no network: the offline page for a
+// navigation, and for the boot of a page the offline page stood in for -
+// the runtime asks for the payload of the url in the address bar, which is
+// the one thing nothing has - the offline page's own payload, which is what
+// the document on screen is. A boot only, no segments header: a navigation
+// while offline still fails as itself, and the page already open keeps its
+// banner. Null when there is no offline page, or nothing of it cached.
+const standIn = async (request) => {
+  if (!OFFLINE_URL) return null
+
+  if (request.mode === 'navigate') return (await caches.match(OFFLINE_URL)) ?? null
+
+  if (request.headers.get('X-RSC') && !request.headers.get('X-RSC-Segments')) {
+    return (
+      (await caches.match(
+        keyFor(new Request(new URL(OFFLINE_URL, self.location.origin), { headers: { 'X-RSC': '1' } })),
+        MATCH,
+      )) ?? null
+    )
+  }
+
+  return null
+}
+
+// The Cache API honours Vary, and a stored payload varies on X-RSC - so a
+// payload warmed with one spelling of that header was a miss for a boot
+// that sent another, and a precached page rendered offline with its payload
+// sitting in the cache, unmatched. What Vary is for is already in the key:
+// the ?__rsc=<segments> above is the one header the answer differs on.
+const MATCH = { ignoreVary: true }
+
 self.addEventListener('fetch', (event) => {
   const request = event.request
   const url = new URL(request.url)
@@ -855,7 +959,7 @@ self.addEventListener('fetch', (event) => {
   // differently for every value of it.
   if (FROZEN.has(url.pathname.replace(/\\/+$/, '') || '/') && !url.search) {
     event.respondWith(
-      caches.match(keyFor(request)).then((hit) => {
+      caches.match(keyFor(request), MATCH).then((hit) => {
         const fresh = fetch(request)
           .then((response) => {
             if (mayStore(response)) {
@@ -865,10 +969,17 @@ self.addEventListener('fetch', (event) => {
 
             return response
           })
-          .catch((error) => {
+          .catch(async (error) => {
             if (hit) return hit
 
-            throw error
+            // Stored by the build but never visited from this browser, so
+            // nothing is cached for it, and no network: the offline page is
+            // the honest answer, the same as for any other navigation - and
+            // its payload for the boot that follows, so the page it stood
+            // in for hydrates. Without this a frozen page failed with
+            // ERR_FAILED where an unstored one showed /offline, and then
+            // stood inert where an unstored one hydrated.
+            return (await standIn(request)) ?? Promise.reject(error)
           })
 
         // Not awaited when there is a hit: the point is that the visitor does
@@ -893,11 +1004,11 @@ self.addEventListener('fetch', (event) => {
           // cached, and a reload with no network has the markup and nothing to
           // hydrate it with.
           //
-          // \`X-RSC: true\` and no segments header is exactly what a fresh boot
+          // \`X-RSC: 1\` and no segments header is exactly what a fresh boot
           // sends, which is what makes this entry the one it finds: the server
           // varies on those, and the Cache API matches on the same.
           if (request.mode === 'navigate') {
-            const warm = new Request(request.url, { headers: { 'X-RSC': 'true' } })
+            const warm = new Request(request.url, { headers: { 'X-RSC': '1' } })
 
             fetch(warm)
               .then((payload) => {
@@ -932,7 +1043,7 @@ self.addEventListener('fetch', (event) => {
         return response
       })
       .catch(async () => {
-        const hit = await caches.match(keyFor(request))
+        const hit = await caches.match(keyFor(request), MATCH)
 
         if (hit) return hit
 
@@ -947,11 +1058,9 @@ self.addEventListener('fetch', (event) => {
         // stand in for another: it is about being offline, not about the url it
         // appears under. Navigations only — a payload request answered with a
         // document would be decoded as one and throw.
-        if (OFFLINE_URL && request.mode === 'navigate') {
-          const page = await caches.match(OFFLINE_URL)
+        const stood = await standIn(request)
 
-          if (page) return page
-        }
+        if (stood) return stood
 
         // Letting it fail says what is true, and a page already open is
         // unaffected.
@@ -1066,17 +1175,24 @@ function writeWebManifest(clientDir, options) {
  * precached and found wanting at the one moment it matters, and the build says
  * which read did it.
  */
-function offlineFallback(frozen, results) {
+export function offlineFallback(frozen, results) {
     const found = results.find((r) => r.url === "/offline");
     if (!found)
         return null;
     if (!frozen.includes("/offline")) {
         // The reason already reads "dynamic — called cookies()", and this sentence
         // has said "not stored" by the time it gets there, so the prefix would say
-        // it twice with a dash in the middle of both.
-        const why = found.reason?.replace(/^dynamic — /, "") ?? null;
+        // it twice with a dash in the middle of both. A shell's reason is a
+        // sentence of its own - "connection() awaited by AuthLinks streams per
+        // request; the rest is stored" - and takes no "it" in front, and the
+        // part about the rest being stored is not the point here.
+        const why = found.type === "shell"
+            ? (found.reason?.replace(/; the rest is stored$/, "") ?? null)
+            : found.reason
+                ? "it " + found.reason.replace(/^dynamic — /, "")
+                : null;
         log("offline: /offline cannot be the fallback" +
-            (why ? `, because it ${why}` : "") +
+            (why ? `, because ${why}` : "") +
             ". A fallback has to be servable with no network at all.");
         return null;
     }
@@ -1102,6 +1218,24 @@ function copyServiceWorkerExtra(clientDir) {
     copyFileSync(source, join(clientDir, "sw-app.js"));
     return "/sw-app.js";
 }
+/**
+ * Whether a public file is worth fetching before it is asked for.
+ *
+ * The precache is what lets the app boot with no network: the scripts, the
+ * stylesheets, the fonts, the manifest and its icons. Everything else in
+ * public/ - an image, a wasm module, the share card - is cached the first
+ * time it is used, which is what the fetch handler does for any hashed
+ * asset. Precaching all of it made an install cost a megabyte before the
+ * visitor had seen a page: 765 kB of it a webp encoder, the rest a png no
+ * browser ever renders.
+ */
+export function bootsTheApp(file) {
+    if (/\.(?:m?js|css|woff2?|webmanifest|json)$/i.test(file))
+        return !/\.wasm\.js$/i.test(file);
+    if (/(?:^|\/)(?:icon|apple-icon|favicon)[^/]*\.(?:png|ico|svg)$/i.test(file))
+        return true;
+    return false;
+}
 function writeServiceWorker(clientDir, frozen = [], offlineUrl = null) {
     if (!existsSync(clientDir))
         return;
@@ -1120,7 +1254,7 @@ function writeServiceWorker(clientDir, frozen = [], offlineUrl = null) {
             const path = join(dir, entry.name);
             if (entry.isDirectory())
                 walk(path, `${prefix}${entry.name}/`);
-            else
+            else if (bootsTheApp(`${prefix}${entry.name}`))
                 files.push(`${prefix}${entry.name}`);
         }
     };
@@ -1607,7 +1741,7 @@ function renderRouteTypes(manifest) {
         "",
         "// `export {}` is load-bearing: in a file with no import or export,",
         "// `declare module` *replaces* the real module rather than augmenting it,",
-        "// and Href and route() vanish from it with no error to explain why.",
+        "// and Route and route() vanish from it with no error to explain why.",
         "export {}",
         "",
         "declare module '@rsc-kit/core/routes' {",
@@ -1723,8 +1857,20 @@ function componentName(absPath) {
     const rel = relative(sourceDir, absPath).replace(/\\/g, "/");
     return rel.replace(/\.(tsx|jsx|ts|js)$/, "");
 }
-function toAlias(name) {
-    return "_c_" + name.replace(/[^a-zA-Z0-9]/g, "_");
+/**
+ * The identifier a route file is imported as in the generated entries.
+ *
+ * One-to-one with the path, which the obvious "replace everything odd with an
+ * underscore" is not: app/agent-account/page and app/agent/account/page
+ * both came out as _c_app_agent_account_page, and the entry declared the
+ * same import twice. A slash is an underscore, because that is what every
+ * alias reads like; anything else that is not a letter or digit - a hyphen,
+ * a dot, the brackets of a param, the parens of a group, an underscore of
+ * its own - is its character code, so no two paths share an alias.
+ */
+export function toAlias(name) {
+    return ("_c_" +
+        name.replace(/[^a-zA-Z0-9]/g, (char) => (char === "/" ? "_" : "$" + char.charCodeAt(0).toString(16))));
 }
 const components = new Map();
 /**
@@ -1736,6 +1882,48 @@ const components = new Map();
  * a default component.
  */
 const apiRoutes = new Map();
+const OPENAPI_ROUTE_ID = "virtual:rsc-kit/openapi";
+/**
+ * /openapi.json, when asked for, registered as an api route at the path the
+ * option names. Synthesised like a sitemap: stored by the build, without
+ * middleware - a document exists to be read.
+ */
+function registerOpenApiRoutes() {
+    if (!openapi)
+        return;
+    const name = `app${openapi.path.replace(/\/$/, "")}/route`;
+    if (apiRoutes.has(name)) {
+        throw new Error(`[rsc-kit] ${openapi.path} is answered by ${apiRoutes.get(name).absPath} and by rscKit({ openapi }). Move one.`);
+    }
+    apiRoutes.set(name, { name, absPath: OPENAPI_ROUTE_ID, methods: ["GET"], generated: { kind: "openapi", file: "" } });
+}
+/** The module behind the synthesised /openapi.json route. */
+function openApiPlugin() {
+    return {
+        name: "rsc-kit:openapi",
+        resolveId(id) {
+            if (id === OPENAPI_ROUTE_ID)
+                return "\0" + id;
+        },
+        load(id) {
+            if (id !== "\0" + OPENAPI_ROUTE_ID || !openapi)
+                return;
+            // Every route.ts the app wrote, imported so its schemas can describe
+            // themselves at request time; the synthesised ones are not an API.
+            const routes = [...apiRoutes.values()].filter((r) => !r.generated);
+            const guarded = new Set((routeManifest().apis ?? []).filter((api) => api.middleware.length > 0).map((api) => api.name));
+            const imports = routes.map((r, i) => `import * as __r${i} from ${JSON.stringify(r.absPath)}`);
+            const entries = routes.map((r, i) => `  { pattern: ${JSON.stringify(patternOf(urlSegments(r.name)))}, methods: ${JSON.stringify(r.methods)}, guarded: ${guarded.has(r.name)}, module: __r${i} }`);
+            return [
+                ...imports,
+                `import { openApiResponse } from ${JSON.stringify(join(packageDir, "openapi"))}`,
+                `const routes = [\n${entries.join(",\n")}\n]`,
+                `export const GET = () => openApiResponse(routes, ${JSON.stringify(openapi.document)})`,
+                "",
+            ].join("\n");
+        },
+    };
+}
 /** Files beside the root layout served at the root as they are: robots.txt, a hand-written sitemap.xml, humans.txt. */
 let rootFiles = [];
 const METADATA_ROUTE_ID = "virtual:rsc-kit/metadata-route/";
@@ -2071,6 +2259,9 @@ const NITRO_HANDLER_OPTIONS = `    props: (match, request) => ({
       ...Object.fromEntries(new URL(request.url).searchParams),
     }),
     version: process.env.RSC_BUILD_VERSION,
+    // A built server gzips what it answers, where the runtime can; the dev
+    // server answers raw, which is what a person reading a response wants.
+    compress: import.meta.env.PROD,
 `;
 const NITRO_HOST_CALLS = `
 let hostInstalled = false
@@ -2199,12 +2390,12 @@ import { DefaultRouteError } from ${JSON.stringify(join(packageDir, "js/DefaultR
 import { searchParams as requestSearchParams } from ${JSON.stringify(join(packageDir, "request"))}
 import { parseParams, parseSearchParams, parseBody, isSearchParamsError, isBodyError } from ${JSON.stringify(join(packageDir, "routeSchema"))}
 import { notFoundDigest, isNotFoundSignal } from ${JSON.stringify(join(packageDir, "notFound"))}
-import { noteRequestRead } from ${JSON.stringify(join(packageDir, "request"))}
+import { noteRequestRead, urlOf } from ${JSON.stringify(join(packageDir, "request"))}
 import { redirectDigest } from ${JSON.stringify(join(packageDir, "redirectDigest"))}
 import { createRscHandler } from ${JSON.stringify(join(packageDir, "host"))}
 import { httpHostCalls } from ${JSON.stringify(join(packageDir, "hostCalls"))}
 import { prerenderedBeside } from ${JSON.stringify(join(packageDir, "files"))}
-import { renderToReadableStream, decodeReply, loadServerAction } from '@vitejs/plugin-rsc/rsc'
+import { renderToReadableStream, decodeReply, decodeAction, decodeFormState, loadServerAction } from '@vitejs/plugin-rsc/rsc'
 import { isQuery, queryCacheControl, isQueryValidationError } from ${JSON.stringify(join(packageDir, "query"))}
 import { isActionValidationError, isClientBuilt } from ${JSON.stringify(join(packageDir, "action"))}
 import { noteFallback as noteCaughtRead } from ${JSON.stringify(join(packageDir, "request"))}
@@ -2364,7 +2555,10 @@ export async function handleApiRoute(
       // reaches for the value.
       noteRequestRead('searchParams')
 
-      return parseSearchParams(mod.searchParams, new URL(request.url).searchParams)
+      // Through urlOf, so the build's probe books this read to searchParams
+      // rather than to the url - a route reads request.url itself when it
+      // wants the query the Next way, and that read is the one that matters.
+      return parseSearchParams(mod.searchParams, new URL(urlOf(request)).searchParams)
     }),
     body: hasBody(method) ? lazily(() => parseBody(mod.body, request)) : undefined,
   }
@@ -3215,8 +3409,18 @@ async function runMiddleware(component: string, props: Record<string, unknown> =
     }
 
     // Sequential and awaited, outermost first: an outer guard refusing means
-    // the inner one should never have been asked.
-    await guard(props)
+    // the inner one should never have been asked. A directory may declare
+    // several as a list - reused checks imported from one place - and they
+    // run in the order written, stopping at the first refusal.
+    for (const check of Array.isArray(guard) ? guard : [guard]) {
+      if (typeof check !== 'function') {
+        throw new Error(
+          'Route middleware ' + name + ' exports something that is not a function or a list of them.',
+        )
+      }
+
+      await check(props)
+    }
   }
 }
 
@@ -3315,6 +3519,54 @@ export async function handleRscHtmlStream(
   return { htmlStream, rscPayloadPromise, clientChunks: {} }
 }
 
+/**
+ * A form posted to the page before the page had a runtime.
+ *
+ * React writes the action's id into the form it emits for a server action,
+ * so a browser with no javascript yet - or none at all - posts the fields
+ * to the page's own url. The action runs from those fields, exactly as it
+ * would have been called, and the page renders afterwards with what it
+ * returned as React's form state: a useActionState form shows its result,
+ * a redirect() thrown by the action leaves through the scope the way a
+ * page's would, and a cookie it set is on the answer.
+ */
+export async function handleRscFormPost(
+  component: string,
+  props: Record<string, unknown> = {},
+  layouts: LayoutEntry[] = [],
+  loadings: string[] = [],
+  parallelSlots: Record<string, string> = {},
+  slotOverrides: Record<string, SlotOverride> = {},
+  nonce?: string,
+  pageKey = '',
+  bootstrap = true,
+  formData: FormData = new FormData(),
+): Promise<{ htmlStream: ReadableStream }> {
+  await instrumented()
+  applyHost()
+  await runMiddleware(component, props)
+
+  // The function the form named, bound to what it posted. Nothing named -
+  // a plain form posted here by mistake - and the page simply renders.
+  const action = await decodeAction(formData)
+  let formState: unknown
+
+  if (action) {
+    const result = await action()
+
+    formState = await decodeFormState(result, formData)
+  }
+
+  const flight = renderToReadableStream(
+    await renderTree(component, props, layouts, loadings, parallelSlots, slotOverrides, 0, pageKey, bootstrap),
+    { onError: flightOnError },
+  )
+  const ssr = await (import.meta as any).viteRsc.loadModule('ssr', 'index')
+  const htmlStream = await ssr.handleSsr(flight, nonce, undefined, bootstrap, formState)
+
+  return { htmlStream }
+}
+
 /**
  * Finish a shell that was frozen at build time.
  *
@@ -3941,7 +4193,7 @@ export async function handleRscPprShell(
     // say so on the route's line; the digest goes into the document for the
     // browser to recognise.
     if ((e as { digest?: string } | null)?.digest === 'rsc-kit:search-params-fallback') {
-      const where = /at ([A-Z][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
+      const where = /at ([A-Z_$][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
       noteCaughtRead('useSearchParams()' + (where ? ' in ' + where : ''))
       return 'rsc-kit:search-params-fallback'
     }
@@ -4091,6 +4343,7 @@ async function serve(request: Request): Promise<Response> {
       handleRsc,
       handleRscStream,
       handleRscHtmlStream,
+      handleRscFormPost,
       handleRscRevalidate,
       handleRscPayload,
       handleRscPprShell,
@@ -4181,6 +4434,8 @@ function generateEntrySsr() {
     const devUrls = join(packageDir, "devUrls");
     const request = join(packageDir, "request");
     const fallbackReport = join(packageDir, "js/fallbackReport");
+    const redirectDigestModule = join(packageDir, "redirectDigest");
+    const notFoundModule = join(packageDir, "notFound");
     return `// GENERATED by rscKit() — do not edit.
 import { createFromReadableStream } from '@vitejs/plugin-rsc/ssr'
 import { renderToReadableStream, resume } from 'react-dom/server.edge'
@@ -4188,6 +4443,8 @@ import { prerender } from 'react-dom/static.edge'
 import { rewriteViteDevUrlStream } from ${JSON.stringify(devUrls)}
 import { noteFallback } from ${JSON.stringify(request)}
 import { cancelledByConsumer, caughtByLoading } from ${JSON.stringify(fallbackReport)}
+import { parseRedirectDigest } from ${JSON.stringify(redirectDigestModule)}
+import { isNotFoundDigest } from ${JSON.stringify(notFoundModule)}
 
 // Set only by the dev server. @vitejs/plugin-rsc emits its bootstrap and CSS
 // links root-relative in dev, which would send the browser to the host for
@@ -4199,6 +4456,7 @@ export async function handleSsr(
   nonce?: string,
   onError?: (error: unknown) => void,
   bootstrap = true,
+  formState?: unknown,
 ): Promise<ReadableStream> {
   const root = await createFromReadableStream(rscStream)
 
@@ -4216,6 +4474,9 @@ export async function handleSsr(
     bootstrapScriptContent,
     nonce,
     onError: onError ?? reportRenderError('ssr'),
+    // What a posted form's action returned, for the useActionState that
+    // asked: React seats it in the form it belongs to.
+    ...(formState !== undefined ? { formState: formState as any } : {}),
   })
 
   return DEV_ORIGIN ? rewriteViteDevUrlStream(html, DEV_ORIGIN) : html
@@ -4255,7 +4516,7 @@ export async function handleSsrPrerender(
     // caught at a boundary is: the build attaches it to the route.
     onError: (error: unknown, info?: { componentStack?: string }) => {
       if ((error as { digest?: string } | null)?.digest !== 'rsc-kit:search-params-fallback') return
-      const where = /at ([A-Z][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
+      const where = /at ([A-Z_$][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
       noteFallback('useSearchParams()' + (where ? ' in ' + where : ''))
       return 'rsc-kit:search-params-fallback'
     },
@@ -4283,11 +4544,18 @@ function reportRenderError(phase: 'ssr' | 'resume') {
 
     const digest = (error as { digest?: string } | null)?.digest
 
+    // A redirect or a notFound() the render asked for arrives here as the
+    // Flight row's error, once per boundary it was thrown in. The rsc side
+    // already turned it into a digest on purpose; it is the page's answer,
+    // and the host reads it off the digest. Not an error to print, four
+    // times or once.
+    if (parseRedirectDigest(digest) || isNotFoundDigest(digest)) return digest
+
     if (digest === 'rsc-kit:search-params-fallback') {
       // The component is the first frame of React's stack. Noted on the
       // request so the build attaches it to the route; printed as one line,
       // not a stack, so the server says which boundary it wants.
-      const where = /at ([A-Z][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
+      const where = /at ([A-Z_$][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
 
       noteFallback('useSearchParams()' + (where ? ' in ' + where : ''))
 
@@ -4381,6 +4649,9 @@ import { refresh } from ${JSON.stringify(refreshModule)}
 createViteRscApp(document, ${JSON.stringify(interceptManifest())}, ${JSON.stringify({
         staticPayloads: staticPayloads || null,
         routes: routesForClient,
+        // Every route.ts, as a url pattern, so a link to one is treated as an
+        // anchor rather than prefetched and fetched as a page.
+        apiRoutes: (routeManifest().apis ?? []).map((api) => patternOf(api.segments)),
     })})
 
 // A server component is not a module the browser has, so Vite cannot replace
@@ -4411,12 +4682,19 @@ ${offline
 // worker answering from a cache in front of it turns every edit into a
 // question about which copy you are looking at.
 if ('serviceWorker' in navigator && import.meta.env.PROD) {
-  window.addEventListener('load', () => {
+  const register = () => {
     void navigator.serviceWorker.register('/sw.js').catch(() => {
       // A worker that will not register is not a reason for the page to fail.
       // The app works; it just will not survive being reloaded offline.
     })
-  })
+  }
+
+  // This runs after the boot payload has been fetched and decoded, and on a
+  // fast load the page has finished loading by then - a listener added now
+  // waits for an event that has already fired, and nothing registered until
+  // the next navigation.
+  if (document.readyState === 'complete') register()
+  else window.addEventListener('load', register)
 }
 `
         : ""}`;
@@ -4664,10 +4942,16 @@ function useSsrModules() {
     return {
         name: "rsc-kit:use-ssr",
         enforce: "pre",
-        applyToEnvironment: (environment) => environment.name === "rsc",
+        applyToEnvironment: (environment) => environment.name === "rsc" || environment.name === "ssr",
         transform(code, id) {
             if (!code.includes("use ssr"))
                 return;
+            // In the environment the module runs in, the directive has done its
+            // work and is a string the bundler warns about. Out it goes.
+            if (this.environment.name === "ssr") {
+                const stripped = withoutSsrDirective(code);
+                return stripped === null ? undefined : { code: stripped, map: null };
+            }
             try {
                 const proxy = ssrProxyModule(code, id);
                 return proxy === null ? undefined : { code: proxy, map: null };
@@ -4687,7 +4971,21 @@ function useSsrModules() {
  * directive that moves it. The build says the same once, as a warning.
  */
 const RENDERER_STUB = "\0rsc-kit:react-dom-server?from=";
-function serverRendererInRsc() {
+/** What react-dom/server exports, across its node, edge and browser entries. */
+const SERVER_RENDERER_EXPORTS = [
+    "renderToString",
+    "renderToStaticMarkup",
+    "renderToReadableStream",
+    "renderToPipeableStream",
+    "renderToStaticNodeStream",
+    "resume",
+    "resumeToPipeableStream",
+    "resumeAndPrerender",
+    "resumeAndPrerenderToNodeStream",
+    "prerender",
+    "prerenderToNodeStream",
+];
+export function serverRendererInRsc() {
     const warned = new Set();
     const appImporter = (ctx, importer) => {
         let current = importer;
@@ -4706,24 +5004,93 @@ function serverRendererInRsc() {
         }
         return importer ? relative(process.cwd(), importer.split("?")[0]) : null;
     };
+    // Per package, so a dependency imported from twenty files is read once.
+    const externalRenderers = new Map();
+    // Packages already named by the warning above, so the stub's own warning
+    // - "imported by node_modules/<package>/dist/index.mjs" - stays quiet for
+    // them: one problem, one line.
+    const warnedPackages = new Set();
     return {
         name: "rsc-kit:server-renderer",
+        // Before Vite's own resolver, which otherwise answers react-dom/server
+        // with React's react-server entry - a real module missing the export,
+        // and a build that fails on MISSING_EXPORT with no mention of the fix.
+        enforce: "pre",
         applyToEnvironment: (environment) => environment.name === "rsc",
-        resolveId(source, importer) {
-            if (!SERVER_RENDERER.test(source))
+        async resolveId(source, importer) {
+            // Only an import from a module: a resolve with no importer is Vite
+            // asking whether the specifier exists - deciding what to externalise -
+            // and answering that with the stub would answer the wrong question.
+            if (SERVER_RENDERER.test(source)) {
+                return importer ? RENDERER_STUB + encodeURIComponent(importer) : undefined;
+            }
+            // A bare import from app code of a package the build leaves external:
+            // its own import of react-dom/server is never resolved here, so the
+            // stub above never sees it. @react-email/render, imported by an
+            // action, built clean and threw React's refusal at the first visitor.
+            // The package is read once for the import, and the build warns the
+            // same way it does for a direct one - naming the app file and the
+            // package - without stubbing a module that may also be used well.
+            if (!importer || importer.includes("/node_modules/") || importer.startsWith("\0"))
+                return;
+            if (!/^(?:@[\w.-]+\/)?[\w.-]+/.test(source) || source.startsWith("."))
+                return;
+            // The generated entries import plugin-rsc, whose ssr half imports the
+            // renderer for its own reasons; that is the build's, not the app's.
+            if (outDir && importer.startsWith(outDir))
+                return;
+            const name = source.startsWith("@") ? source.split("/").slice(0, 2).join("/") : source.split("/")[0];
+            if (name === "react-dom" || name === "react" || name.startsWith("@rsc-kit/") || name.startsWith("@vitejs/"))
+                return;
+            let imports = externalRenderers.get(name);
+            if (imports === undefined) {
+                // Vite answers a dependency either as external, by its bare name,
+                // or by the file it resolved to under node_modules - which of the
+                // two depends on how the environment was set up, and both are a
+                // dependency whose imports the build will not look inside.
+                const resolved = await this.resolve(source, importer, { skipSelf: true });
+                const id = resolved?.id ?? "";
+                const marker = `/node_modules/${name}/`;
+                const at = id.lastIndexOf(marker);
+                const dir = resolved?.external
+                    ? installedPackageDir(name, dirname(importer.split("?")[0]))
+                    : at !== -1
+                        ? id.slice(0, at + marker.length - 1)
+                        : null;
+                imports = dir !== null && importsServerRenderer(dir);
+                externalRenderers.set(name, imports);
+            }
+            if (!imports)
                 return;
-            return RENDERER_STUB + encodeURIComponent(importer ?? "");
+            const message = `${relative(process.cwd(), importer.split("?")[0])} imports ${name}, which imports react-dom/server, and ` +
+                serverRendererMessage(null).replace(/^react-dom\/server cannot run/, "that cannot run");
+            if (!warned.has(message)) {
+                warned.add(message);
+                warnedPackages.add(name);
+                this.warn(message);
+            }
         },
         load(id) {
             if (!id.startsWith(RENDERER_STUB))
                 return;
             const importer = decodeURIComponent(id.slice(RENDERER_STUB.length)) || null;
             const message = serverRendererMessage(appImporter(this, importer));
-            if (this.environment.mode === "build" && !warned.has(message)) {
+            // The last node_modules segment: Bun's store nests the real package
+            // under node_modules/.bun/<pkg>@<v>/node_modules/<pkg>.
+            const viaPackage = [...(importer ?? "").matchAll(/\/node_modules\/((?:@[^/]+\/)?[^/]+)\//g)].at(-1)?.[1];
+            if (this.environment.mode === "build" &&
+                !warned.has(message) &&
+                !(viaPackage && warnedPackages.has(viaPackage))) {
                 warned.add(message);
                 this.warn(message);
             }
-            return `throw new Error(${JSON.stringify(message)});\n`;
+            // Every name the renderer exports, each throwing the fix when called.
+            // A module that threw when loaded took the whole server down at boot
+            // for one action nobody had called yet, and a stub with no exports
+            // failed the build on MISSING_EXPORT with the message scrolled past.
+            const refuse = `() => { throw new Error(${JSON.stringify(message)}) }`;
+            return (SERVER_RENDERER_EXPORTS.map((name) => `export const ${name} = ${refuse};`).join("\n") +
+                `\nexport const version = "0.0.0";\nexport default { ${SERVER_RENDERER_EXPORTS.join(", ")}, version };\n`);
         },
     };
 }
@@ -4911,6 +5278,14 @@ export function rscKit(options = {}) {
         ...RUNTIME_BUILTINS,
         ...[...DEFAULT_SERVER_EXTERNALS, ...(options.serverExternalPackages ?? [])].map(externalPackage),
     ];
+    // Dependencies with a "use client" file that plugin-rsc would leave
+    // external, because they never declared react as a peer. Bundled into the
+    // server graphs so the directive is read, the same as a package that did.
+    const bundledClientPackages = clientPackages(projectRoot);
+    for (const name of bundledClientPackages) {
+        console.warn(`[rsc-kit] bundling ${name}: it has "use client" files but does not declare react ` +
+            "as a peer dependency, so its components would otherwise run on the server.");
+    }
     const routesPlugin = {
         name: "rsc-kit",
         // A Nitro module, which Nitro's Vite plugin collects from any plugin
@@ -4920,9 +5295,49 @@ export function rscKit(options = {}) {
         nitro: {
             name: "rsc-kit",
             setup(nitro) {
-                if (nitro.options.dev || !instrumentationFile())
+                if (nitro.options.dev)
                     return;
+                // External at Nitro's layer too. The Vite build leaves these as
+                // imports, and Nitro would then bundle them into its own chunks -
+                // which for a native package fails at load, and for a polyfill like
+                // reflect-metadata runs it after the chunk that checks for it.
+                // Traced, each is copied into .output/server/node_modules and
+                // imported by the built server the way its author expected.
+                // Only the ones the project has. Nitro's tracer says so, once per
+                // name, for every entry it cannot find - and a list of every native
+                // package anyone might install is mostly ones this app does not.
+                nitro.options.traceDeps = [
+                    ...(nitro.options.traceDeps ?? []),
+                    ...[...DEFAULT_SERVER_EXTERNALS, ...(options.serverExternalPackages ?? [])].filter((name) => installedPackageDir(name, projectRoot) !== null || packageEntryInGraph(projectRoot, name) !== null),
+                ];
+                // The assets, precompressed at build and served with their encoding
+                // by Nitro's own static handler; the host gzips the rest as it
+                // answers. Between them a bun or node server answering the internet
+                // by itself sends nothing raw. A config that set this keeps it.
+                // Nitro's default is a literal false, so ?? would not do; an object
+                // is a configuration and is kept.
+                if (typeof nitro.options.compressPublicAssets !== "object")
+                    nitro.options.compressPublicAssets = true;
                 nitro.options.virtual ??= {};
+                // A polyfill a dependency checks for at module evaluation, loaded
+                // before any service. The bundler places an external import after
+                // the chunk imports of the module that had it, whatever the source
+                // said, so reflect-metadata came up after tsyringe (under
+                // @peculiar/x509, under @simplewebauthn/server) - by luck survivable
+                // run as a directory, fatal compiled into a binary. A Nitro plugin
+                // is evaluated by the entry itself, and the services that carry the
+                // app are loaded lazily after it; imported by file, the polyfill is
+                // inlined there and runs first wherever the server runs. Only for a
+                // project whose graph has it.
+                const polyfills = FIRST_POLYFILLS.map((name) => packageEntryInGraph(projectRoot, name)).filter((entry) => entry !== null);
+                if (polyfills.length) {
+                    nitro.options.virtual["#rsc-kit/polyfills"] =
+                        polyfills.map((entry) => `import ${JSON.stringify(entry)};`).join("\n") +
+                            "\nexport default () => {};\n";
+                    nitro.options.plugins = ["#rsc-kit/polyfills", ...(nitro.options.plugins ?? [])];
+                }
+                if (!instrumentationFile())
+                    return;
                 nitro.options.virtual["#rsc-kit/startup"] = STARTUP_PLUGIN;
                 nitro.options.plugins = [...(nitro.options.plugins ?? []), "#rsc-kit/startup"];
             },
@@ -4938,6 +5353,7 @@ export function rscKit(options = {}) {
             apiRoutes.clear();
             discover(appDir);
             registerMetadataRoutes(appDir);
+            registerOpenApiRoutes();
             siteHosts = ownHosts(rootMetadataBase(appDir), hostsOption);
             // Silent when it worked. The names were printed on every dev start and
             // every build — thirty of them for a middling app, above the output that
@@ -5117,6 +5533,11 @@ export function rscKit(options = {}) {
                     alias: aliasEntries(),
                 },
                 build: { emptyOutDir: true },
+                // What reaches the browser. Vite's own VITE_ prefix, and PUBLIC_ - the
+                // scaffold's spelling, and Next's minus its brand - so a variable
+                // named for a port reads through import.meta.env without a config
+                // line. A config that set its own prefixes keeps them; Vite merges.
+                envPrefix: ["VITE_", "PUBLIC_"],
                 environments: {
                     // Server bundles — stay under the (non-public) out dir. `bun` and
                     // `bun:*` are the runtime's own modules, like `node:*`: nothing to
@@ -5129,6 +5550,8 @@ export function rscKit(options = {}) {
                                 external: serverExternals,
                             },
                         },
+                        resolve: { noExternal: bundledClientPackages },
+                        optimizeDeps: { exclude: bundledClientPackages },
                     },
                     ssr: {
                         build: {
@@ -5137,6 +5560,8 @@ export function rscKit(options = {}) {
                                 external: serverExternals,
                             },
                         },
+                        resolve: { noExternal: bundledClientPackages },
+                        optimizeDeps: { exclude: bundledClientPackages },
                     },
                     // Client bundle — emitted into public/ for the web server to serve.
                     client: {
@@ -5358,8 +5783,12 @@ export function rscKit(options = {}) {
             // when the directory is not there. Only under Nitro, whose presets are
             // the ones without a disk; on its own the plugin serves from outDir.
             if (clientOut && existsSync(staticDir)) {
-                const { inlineModuleName, inlineModuleSource } = await import("./files.js");
+                const { inlineModuleName, inlineModuleSource, compileEntrySource } = await import("./files.js");
                 writeFileSync(join(dirname(staticDir), inlineModuleName(NITRO_STATIC_DIR)), await inlineModuleSource(staticDir));
+                // And the entry a binary is compiled from, so the pages above end up
+                // inside it rather than rendered live: bun build --compile
+                // .output/server/compile.mjs. The scaffold's script names it.
+                writeFileSync(join(dirname(staticDir), "compile.mjs"), compileEntrySource(NITRO_STATIC_DIR));
             }
             // Manifest first. The service worker precaches whatever it finds in this
             // directory, so writing it afterwards leaves it out of the list — and an
@@ -5444,6 +5873,7 @@ export function rscKit(options = {}) {
         useSsrModules(),
         serverRendererInRsc(),
         metadataRoutesPlugin(),
+        openApiPlugin(),
         extendableClientReferences(),
         typecheckPlugin(),
         clientImportsAudit(),