@rsc-kit/core 0.8.0 → 0.10.0

package/dist/vite.js

@@ -13,6 +13,7 @@
 // the structural config (entries, output dirs, base). @vitejs/plugin-rsc is
 // included here so it always runs before any react() layer the app adds.
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { gzipSync } from 'node:zlib';
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -369,6 +370,7 @@ function routeManifest() {
             segments: urlSegments(name),
             layouts: ancestors(name, 'layout').map((n) => n),
             loadings: ancestors(name, 'loading').map((n) => n),
+            errors: ancestors(name, 'error'),
             middleware: ancestors(name, 'middleware').map((n) => n),
             slots,
             sections: names.filter((n) => SECTION_FILE.test(n + '.tsx') && dirOf(n) === dirOf(name)),
@@ -386,6 +388,12 @@ function routeManifest() {
         build: { output, exportPath, payloadName: staticPayloads },
         routes,
         intercepts,
+        apis: [...apiRoutes.values()].map(({ name, methods }) => ({
+            name,
+            segments: urlSegments(name),
+            methods,
+            middleware: ancestors(name, 'middleware'),
+        })),
     };
 }
 /**
@@ -413,10 +421,11 @@ function warnIfTypesUnreachable() {
         const include = JSON.parse(text).include;
         if (!Array.isArray(include))
             return;
-        if (include.some((entry) => typeof entry === 'string' && entry.includes('.rsc-kit')))
-            return;
-        log(`tsconfig.json does not include .rsc-kit, where the generated types are written.\n` +
-            `  Add ".rsc-kit/**/*" to "include", or typed routes and rpc() fall back to string.`);
+        const covers = (what) => include.some((entry) => typeof entry === 'string' && entry.includes(what));
+        if (!covers('.rsc-kit')) {
+            log(`tsconfig.json does not include .rsc-kit, where the generated types are written.\n` +
+                `  Add ".rsc-kit/**/*" to "include", or typed routes and rpc() fall back to string.`);
+        }
     }
     catch {
         // An unparseable tsconfig is the project's own problem, not this one's.
@@ -451,10 +460,6 @@ function writeHostBindings(manifest) {
     // and a typecheck cannot see it. Written whether or not there are actions:
     // server components call it directly too.
     writeFileSync(join(typesDir, 'rsc-env.d.ts'), renderHostGlobalTypes());
-    // The engine's own ambient types, copied where the app's typechecker will
-    // see them. Deliberately a separate file from the one above: this one is
-    // the engine's and identical everywhere, that one is generated from how
-    // this host is configured.
     // The urls this build found, so a link to a page that does not exist fails
     // the typecheck instead of the browser.
     writeFileSync(join(typesDir, 'rsc-routes.d.ts'), renderRouteTypes(manifest));
@@ -463,10 +468,6 @@ function writeHostBindings(manifest) {
     // an app-authored one goes stale — the first version named only RscEngine,
     // which typechecks a server and fails a prerender script.
     writeFileSync(join(typesDir, 'rsc-engine.d.ts'), ENGINE_TYPES);
-    const engineTypes = join(packageDir, 'types.d.ts');
-    if (existsSync(engineTypes)) {
-        writeFileSync(join(typesDir, 'rsc-types.d.ts'), readFileSync(engineTypes, 'utf-8'));
-    }
     warnIfTypesUnreachable();
     const target = join(sourceDir, 'server-actions.generated.ts');
     // A host with no functions of its own leaves no file behind: kept, its
@@ -752,9 +753,10 @@ async function prerenderAfterBundles(bundle, staticDir, assetsDir) {
             'Prerendering renders the app, so it needs the bundle the build just wrote. ' +
             'Build with prerender: false to render every page on demand instead.');
     }
-    const [{ prerender, summary, legend }, { writeTo }] = await Promise.all([
+    const [{ prerender, summary, legend, notes, clientJsSize, pathKey: pathKeyOf }, { writeTo }, { prerenderApiRoutes },] = await Promise.all([
         import('./prerender.js'),
         import('./files.js'),
+        import('./apiPrerender.js'),
     ]);
     // Cleared first: a route that changes classification between builds
     // otherwise leaves its old shell on disk and the host goes on serving it.
@@ -763,22 +765,58 @@ async function prerenderAfterBundles(bundle, staticDir, assetsDir) {
     const engine = (await import(pathToFileURL(bundle).href));
     const mark = { frozen: '○', shell: '◐', blocked: 'ƒ', error: '✗' };
     let failed = 0;
+    // Weighed from the page the prerenderer just wrote, so the column is what
+    // that page actually loads rather than a total every route is charged for.
+    const weigh = weighClientJs(assetsDir);
+    const pending = [];
     const results = await prerender({
         engine,
         write: writeTo(staticDir),
         onResult: (r) => {
             if (r.type === 'error')
                 failed++;
-            console.log(`  ${mark[r.type] ?? ' '}  ${r.url}${r.reason ? `  (${r.reason})` : ''}`);
-            if (r.warning)
-                console.log(`     ⚠  ${r.warning}`);
+            const key = pathKeyOf(r.url);
+            const file = [`${key}.html`, `${key}.ppr.html`]
+                .map((name) => join(staticDir, name))
+                .find((path) => existsSync(path));
+            pending.push({
+                line: `  ${mark[r.type] ?? ' '}  ${r.url}`,
+                bytes: file ? weigh(readFileSync(file, 'utf-8')) : null,
+                extra: [
+                    ...(r.reason ? [`     ${r.reason}`] : []),
+                    ...(r.warning ? [`     ⚠  ${r.warning}`] : []),
+                ],
+            });
         },
     });
+    // After the pages, sharing their output. An api route is a url the build
+    // either answered or could not, which is the same question the table above
+    // is already answering — a second list under its own heading would be two
+    // places to look for one fact.
+    const apis = await prerenderApiRoutes(engine, engine.manifest(), writeTo(staticDir));
+    for (const api of apis) {
+        pending.push({
+            line: `  ${api.type === 'frozen' ? '○' : 'ƒ'}  ${api.url}`,
+            bytes: null,
+            extra: api.reason ? [`     ${api.reason}`] : [],
+        });
+    }
+    // Printed together rather than as each route lands, because a column has to
+    // line up and the widest url is not known until the last one is in.
+    const column = Math.max(...pending.map((p) => p.line.length)) + 2;
+    for (const row of pending) {
+        const size = row.bytes === null ? '' : clientJsSize(row.bytes);
+        console.log(size ? row.line.padEnd(column) + size : row.line);
+        for (const line of row.extra)
+            console.log(line);
+    }
     const count = (type) => results.filter((r) => r.type === type).length;
+    const note = notes(results);
+    const counted = [...results, ...apis];
     console.log(`
-${legend(results)}
+${legend(counted)}
 
-  ${summary(results)}`);
+  ${summary(counted)}${note ? `\n\n${note}` : ''}`);
     if (failed > 0) {
         throw new Error(`[rsc-kit] ${failed} route${failed === 1 ? '' : 's'} failed to render.\n` +
             'Prerendering runs your app: whatever those pages need at render time has to be\n' +
@@ -787,6 +825,49 @@ ${legend(results)}
     if (output === 'export')
         await exportAfterPrerender(results, staticDir, assetsDir);
 }
+/**
+ * Weighs the javascript one stored page makes the browser download.
+ *
+ * Read back out of the html rather than worked out from the module graph,
+ * because the html is the answer: React writes a modulepreload for every chunk
+ * the page needs, so whatever is in there is what the browser fetches. Nothing
+ * here has to agree with the bundler about anything.
+ *
+ * Gzipped, and each chunk weighed once however many pages name it — the same
+ * three files appear on every route and compressing them per page is the whole
+ * cost of this function.
+ *
+ * Returns null when there is no page to weigh, which is a route rendered on
+ * demand. A build must not fail over a column it prints for information.
+ */
+function weighClientJs(assetsDir) {
+    const weighed = new Map();
+    const bytesOf = (asset) => {
+        const cached = weighed.get(asset);
+        if (cached !== undefined)
+            return cached;
+        const file = join(assetsDir, asset);
+        const bytes = existsSync(file) ? gzipSync(readFileSync(file)).byteLength : 0;
+        weighed.set(asset, bytes);
+        return bytes;
+    };
+    return (html) => {
+        if (!html)
+            return null;
+        const named = new Set();
+        // Split rather than matched: /assets/name.js is the only shape written, and
+        // a regex over a whole document is the slower half of this function.
+        for (const piece of html.split('/assets/').slice(1)) {
+            const name = piece.split(/["'\s)]/)[0];
+            if (name.endsWith('.js'))
+                named.add('assets/' + name);
+        }
+        let total = 0;
+        for (const asset of named)
+            total += bytesOf(asset);
+        return total;
+    };
+}
 /**
  * Turn the frozen output into a directory a static host can serve.
  *
@@ -907,7 +988,9 @@ function renderHostGlobalTypes() {
     ].join('\n');
 }
 // ── Discovery ────────────────────────────────────────────────────────────────
-const ROUTE_FILES = ['page', 'layout', 'loading', 'default', 'middleware'];
+const ROUTE_FILES = ['page', 'layout', 'loading', 'error', 'not-found', 'default', 'middleware'];
+/** The methods a route.ts may export. HEAD and OPTIONS are answered for you. */
+const API_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
 /** `orders.section.tsx` — a region of a page that can be refreshed by name. */
 const SECTION_FILE = /\.section\.(tsx|jsx|ts|js)$/;
 const EXTS = ['tsx', 'jsx', 'ts', 'js'];
@@ -927,6 +1010,15 @@ function toAlias(name) {
     return '_c_' + name.replace(/[^a-zA-Z0-9]/g, '_');
 }
 const components = new Map();
+/**
+ * `route.ts` files, by the name a url is matched against.
+ *
+ * Kept apart from `components` on purpose: these are not React and never enter
+ * the render. They are imported by the generated entry and called with a
+ * Request, which is why they can export whatever methods they like rather than
+ * a default component.
+ */
+const apiRoutes = new Map();
 function register(absPath) {
     const name = componentName(absPath);
     const existing = components.get(name);
@@ -937,12 +1029,42 @@ function register(absPath) {
     return c;
 }
 /** Walk app/ collecting page/layout/loading/default/middleware components. */
+/**
+ * Record a route.ts and the methods it exports.
+ *
+ * Syntactic, deliberately. A handler assembled at runtime is not found, which
+ * errs toward refusing a file whose shape we would be guessing at rather than
+ * registering a url that answers 405 to everything.
+ */
+function registerApiRoute(absPath) {
+    const name = componentName(absPath);
+    const source = readFileSync(absPath, 'utf-8');
+    const methods = API_METHODS.filter((method) => new RegExp(`^\\s*export\\s+(?:async\\s+function|function|const|let|var)\\s+${method}\\b`, 'm').test(source));
+    if (methods.length === 0) {
+        // `route.ts` is also where a host declares the guards for everything below
+        // it — the file predates api routes and is still read that way. One that
+        // exports middleware is that file, not an endpoint, and saying so would be
+        // telling someone their working config is broken.
+        if (/^\s*export\s+(?:const|let|var|function)\s+middleware\b/m.test(source))
+            return;
+        throw new Error(`[rsc-kit] ${relative(projectRoot, absPath)} exports no request methods.\n` +
+            `  Export one named for the method it answers — export function GET(request: Request) — ` +
+            `or delete the file. One of: ${API_METHODS.join(', ')}.`);
+    }
+    apiRoutes.set(name, { name, absPath, methods });
+}
 function discover(dir) {
     for (const base of ROUTE_FILES) {
         const p = findRouteFile(dir, base);
         if (p)
             register(p);
     }
+    // route.ts — an api endpoint, colocated with the pages it sits among. Read
+    // for its method exports here rather than at request time, so a route that
+    // exports nothing callable is a build error instead of a 404 nobody explains.
+    const api = findRouteFile(dir, 'route');
+    if (api)
+        registerApiRoute(api);
     // Named regions. Registered like any other component so the generated entry
     // imports them — which is what runs section() and puts the name in the
     // registry the server looks up to re-render one on its own.
@@ -997,6 +1119,25 @@ function hasStaticParams(absPath) {
     const src = readFileSync(absPath, 'utf-8');
     return /export\s+((async\s+)?function\s+generateStaticParams|const\s+generateStaticParams)/.test(src);
 }
+/**
+ * Which url schemas a page exports.
+ *
+ * Read from the source rather than by importing the module, the same way
+ * metadata and generateStaticParams are: this runs while the graph is being
+ * generated, and importing a page here would pull the app's whole server tree
+ * into the plugin.
+ *
+ * `const` only. A schema is a value — `export function params` would be a
+ * function, which no Standard Schema is, so matching it would generate an
+ * import for something that can never validate.
+ */
+function urlSchemaExports(absPath) {
+    const src = readFileSync(absPath, 'utf-8');
+    return {
+        params: /export\s+const\s+params\s*[=:]/.test(src),
+        searchParams: /export\s+const\s+searchParams\s*[=:]/.test(src),
+    };
+}
 // ── Codegen ──────────────────────────────────────────────────────────────────
 /**
  * The dev fall-through, emitted only when there is a backend to hand a url to.
@@ -1153,10 +1294,28 @@ function installHostCallsOnce(): void {
 
 `;
 function generateEntryRsc(fallbackOrigin = '') {
+    // The 404 page, if the app has one, and the layouts it renders inside.
+    // Computed here rather than looked up at runtime: not-found is not a route,
+    // so the manifest has no entry to read its chain from.
+    const notFoundComponent = [...components.keys()].find((name) => name.endsWith('/not-found'));
+    const notFoundLayouts = notFoundComponent
+        ? [...components.keys()]
+            .filter((name) => name.endsWith('/layout') &&
+            notFoundComponent.startsWith(name.slice(0, -'layout'.length)))
+            .sort((a, b) => a.length - b.length)
+        : [];
     const imports = [];
     const mapEntries = [];
     const metaEntries = [];
     const paramEntries = [];
+    const schemaEntries = [];
+    const apiEntries = [];
+    // Namespace imports: a route.ts exports one function per method, and which
+    // ones it exports is the thing the dispatcher needs.
+    for (const [index, route] of [...apiRoutes.values()].entries()) {
+        imports.push(`import * as __api${index} from ${JSON.stringify(route.absPath)}`);
+        apiEntries.push(`  ${JSON.stringify(route.name)}: __api${index},`);
+    }
     for (const c of components.values()) {
         imports.push(`import ${c.alias} from ${JSON.stringify(c.absPath)}`);
         mapEntries.push(`  ${JSON.stringify(c.name)}: ${c.alias},`);
@@ -1175,6 +1334,15 @@ function generateEntryRsc(fallbackOrigin = '') {
             imports.push(`import * as ${c.alias}_params from ${JSON.stringify(c.absPath)}`);
             paramEntries.push(`  ${JSON.stringify(c.name)}: ${c.alias}_params.generateStaticParams,`);
         }
+        const urlSchemas = urlSchemaExports(c.absPath);
+        if (urlSchemas.params || urlSchemas.searchParams) {
+            imports.push(`import * as ${c.alias}_schema from ${JSON.stringify(c.absPath)}`);
+            const fields = [
+                urlSchemas.params ? `params: ${c.alias}_schema.params` : null,
+                urlSchemas.searchParams ? `searchParams: ${c.alias}_schema.searchParams` : null,
+            ].filter(Boolean);
+            schemaEntries.push(`  ${JSON.stringify(c.name)}: { ${fields.join(', ')} },`);
+        }
     }
     // The engine's own modules are named without an extension: this plugin runs
     // from src/ in its own repo and from dist/ once published, and Vite resolves
@@ -1183,15 +1351,18 @@ function generateEntryRsc(fallbackOrigin = '') {
 import { SegmentBoundary } from ${JSON.stringify(join(packageDir, "js/SegmentBoundary"))}
 import { DocumentTitle } from ${JSON.stringify(join(packageDir, "js/DocumentTitle"))}
 import { SlotBoundary } from ${JSON.stringify(join(packageDir, "js/SlotBoundary"))}
+import { RouteErrorBoundary } from ${JSON.stringify(join(packageDir, "js/RouteErrorBoundary"))}
 import { sectionComponent } from ${JSON.stringify(join(packageDir, "js/section"))}
 import { PathnameProvider } from ${JSON.stringify(join(packageDir, "js/PathnameProvider"))}
 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 { 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 { isQuery, queryCacheControl } from ${JSON.stringify(join(packageDir, 'query'))}
+import { isQuery, queryCacheControl, isQueryValidationError } from ${JSON.stringify(join(packageDir, 'query'))}
 import { Suspense, createElement, Fragment } from 'react'
 import { AsyncLocalStorage } from 'node:async_hooks'
 ${imports.join('\n')}
@@ -1204,6 +1375,113 @@ const components: Record<string, any> = {
 ${mapEntries.join('\n')}
 }
 
+/**
+ * The url schemas a page exported, by component name.
+ *
+ * Empty for a page that exported none, which is the common case — the lookup
+ * below then hands the url through untouched and costs a property read.
+ */
+const urlSchemas: Record<string, { params?: any; searchParams?: any }> = {
+${schemaEntries.join('\n')}
+}
+
+/** route.ts modules, by the name the manifest matched. */
+const apiRoutes: Record<string, any> = {
+${apiEntries.join('\n')}
+}
+
+/**
+ * Answer an api route.
+ *
+ * The handler is handed an ordinary Request and the route params, and whatever
+ * Response it returns is the answer. Nothing renders; there is no payload and
+ * no client involved.
+ *
+ * HEAD falls back to GET, which is what the spec says it is — the same response
+ * without a body. Answering 405 instead breaks link checkers and anything that
+ * probes before it fetches.
+ */
+/** Whether a method may carry a body worth reading. */
+function hasBody(method: string): boolean {
+  return method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE'
+}
+
+/**
+ * What an api route answers when its own schema refused the request.
+ *
+ * Three statuses, because the three failures are three different things and
+ * collapsing them would leave a client unable to tell a url that names nothing
+ * from one it addressed wrongly:
+ *
+ *   404  the params do not describe a resource - the url names nothing
+ *   400  the query string is wrong - the resource exists, the request did not
+ *   422  the body is wrong - the same status an action returns for the same
+ *        failure, so a client has one shape to handle
+ */
+function refusedInput(error: unknown): Response {
+  const json = (status: number, payload: unknown) =>
+    new Response(JSON.stringify(payload), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })
+
+  if (isNotFoundSignal(error)) return json(404, { message: 'Not found' })
+
+  if (isSearchParamsError(error)) {
+    return json(400, { message: error.message, errors: error.errors })
+  }
+
+  if (isBodyError(error)) return json(422, { message: error.message, errors: error.errors })
+
+  throw error
+}
+
+export async function handleApiRoute(
+  name: string,
+  request: Request,
+  params: Record<string, string>,
+  allow: string,
+): Promise<Response> {
+  applyHost()
+
+  const mod = apiRoutes[name]
+  const method = request.method
+  const handler = mod?.[method] ?? (method === 'HEAD' ? mod?.GET : undefined)
+
+  if (!handler) {
+    // Allow is not optional on a 405: without it a client cannot tell which
+    // methods would have worked, and neither can a person reading the logs.
+    return new Response('Method not allowed', { status: 405, headers: { Allow: allow } })
+  }
+
+  // Schemas are optional, per route and per kind. A route that exported none
+  // reaches the handler with exactly what it always did — the raw params, the
+  // URLSearchParams, and a body nobody has read — so nothing written before
+  // this existed changes behaviour.
+  let input
+  try {
+    input = {
+      params: await parseParams(mod.params, params),
+      searchParams: await parseSearchParams(
+        mod.searchParams,
+        new URL(request.url).searchParams,
+      ),
+      body: hasBody(method) ? await parseBody(mod.body, request) : undefined,
+    }
+  } catch (error) {
+    return refusedInput(error)
+  }
+
+  const answer = await handler(request, input)
+
+  // A HEAD answered by GET must not carry a body.
+  if (method === 'HEAD' && answer instanceof Response) {
+    return new Response(null, { status: answer.status, headers: answer.headers })
+  }
+
+  return answer
+}
+
 const metadataMap: Record<string, { static?: any; generate?: (p: any) => any }> = {
 ${metaEntries.join('\n')}
 }
@@ -1340,11 +1618,95 @@ function ownerLayoutIndex(slotComponent: string, layouts: LayoutEntry[]): number
  * nothing wrong. Awaiting it still surfaces the real error.
  */
 function pageSearchParams(): Promise<URLSearchParams> {
-  const pending = requestSearchParams()
+  // Lazy. Every page is handed this whether it reads it or not, and reading the
+  // request is what marks a page as needing one — so starting it eagerly told
+  // the build that every page was dynamic, and put url() beside every route in
+  // the output as though someone had written it.
+  //
+  // A thenable rather than a promise, so nothing happens until a page awaits.
+  let pending: Promise<URLSearchParams> | null = null
+
+  const start = (): Promise<URLSearchParams> => {
+    if (!pending) {
+      pending = requestSearchParams()
+
+      // Attached here for the same reason it always was: during a prerender
+      // this never settles, and an unobserved rejection ends the process.
+      pending.catch(() => {})
+    }
+
+    return pending
+  }
+
+  return {
+    then: (ok, fail) => start().then(ok, fail),
+    catch: (fail) => start().catch(fail),
+    finally: (done) => start().finally(done),
+  } as Promise<URLSearchParams>
+}
+
+/**
+ * A page's params, through its own schema if it exported one.
+ *
+ * Laziness is preserved on purpose. The params promise may be one that never
+ * settles - that is how the prerender probe says "not for any particular url"
+ * - so this must not await eagerly. Chaining keeps a never-settling promise
+ * never-settling, and the schema runs only if the page reads it.
+ */
+function checkedParams(
+  schemas: { params?: any } | undefined,
+  params: Promise<Record<string, unknown>>,
+): Promise<unknown> {
+  if (!schemas || !schemas.params) return params
+
+  return params.then((value) => parseParams(schemas.params, value))
+}
+
+/**
+ * A page's query string, through its own schema if it exported one.
+ *
+ * Wrapped as a thenable rather than chained, so a page that never reads the
+ * query still never starts the read - the whole thing pageSearchParams exists
+ * to guarantee. Calling .then on it here would start it for every page, and
+ * every page would be reported as reading the request.
+ */
+function checkedSearchParams(
+  schemas: { searchParams?: any } | undefined,
+  search: Promise<URLSearchParams>,
+): Promise<unknown> {
+  if (!schemas || !schemas.searchParams) return search
+
+  let pending: Promise<unknown> | null = null
+
+  const start = (): Promise<unknown> => {
+    if (!pending) {
+      pending = search.then((value) => parseSearchParams(schemas.searchParams, value))
+      pending.catch(() => {})
+    }
+
+    return pending
+  }
 
-  pending.catch(() => {})
+  return {
+    then: (ok, fail) => start().then(ok, fail),
+    catch: (fail) => start().catch(fail),
+    finally: (done) => start().finally(done),
+  } as Promise<unknown>
+}
+
+let errorChains: Record<string, string[]> | null = null
+
+/** The error.tsx files above a component, outermost first. */
+function errorChain(component: string): string[] {
+  if (!errorChains) {
+    errorChains = {}
+
+    for (const route of manifest().routes as { component: string; errors?: string[] }[]) {
+      if (route.errors?.length) errorChains[route.component] = route.errors
+    }
+  }
 
-  return pending
+  return errorChains[component] ?? []
 }
 
 // Composition: layout(outer..inner) > Suspense(loading, innermost-first) > page.
@@ -1372,13 +1734,39 @@ function buildElement(
   // and renders to completion during the probe — producing a page about an
   // invented value, right for nothing — which is why such a route could only
   // ever be rendered per request.
-  let element = createElement(Component, { params, searchParams: pageSearchParams() })
+  const schemas = urlSchemas[component]
+
+  let element = createElement(Component, {
+    params: checkedParams(schemas, params),
+    searchParams: checkedSearchParams(schemas, pageSearchParams()),
+  })
 
   for (let i = loadings.length - 1; i >= 0; i--) {
     const Loading = components[loadings[i]]
     element = createElement(Suspense, { fallback: Loading ? createElement(Loading) : null }, element)
   }
 
+  // Outside the Suspense boundary, innermost first — the nearest error.tsx to
+  // the failure answers, the same rule loading.tsx follows. Outside, so a
+  // component that throws while its fallback is showing is still caught.
+  //
+  // Read from the route table rather than passed in, for the same reason the
+  // middleware chain is: every render path is covered by construction, and no
+  // caller has to remember to forward them.
+  const errors = errorChain(component)
+
+  for (let i = errors.length - 1; i >= 0; i--) {
+    const Fallback = components[errors[i]]
+
+    if (!Fallback) continue
+
+    element = createElement(
+      RouteErrorBoundary,
+      { fallback: Fallback as never, resetKey: pageKey || component },
+      element,
+    )
+  }
+
   // <title>/<meta> go OUTSIDE the Suspense boundaries so they reach the shell
   // immediately — inside, they would be withheld until the page's data
   // resolves, delaying the whole document on a slow page.
@@ -1492,7 +1880,14 @@ async function renderTree(
       if (bootstrap) head.push(createElement(DocumentTitle, { key: '__ts', title: String(md.title) }))
     }
     if (md.description != null) head.push(createElement('meta', { key: '__d', name: 'description', content: String(md.description) }))
-    for (const [k, v] of Object.entries(md)) {
+    // other is flattened in beside the named keys, because it is a place to put
+    // meta tags rather than a meta tag by that name. A key at the top level
+    // still renders — the type no longer invites one, but an app written
+    // against the old shape must not silently lose its tags.
+    const named = Object.entries(md).filter(([k]) => k !== 'other')
+    const extra = Object.entries((md.other ?? {}) as Record<string, unknown>)
+
+    for (const [k, v] of [...named, ...extra]) {
       if (k === 'title' || k === 'description' || v == null) continue
       head.push(createElement('meta', { key: '__m_' + k, name: k, content: String(v) }))
     }
@@ -1608,6 +2003,13 @@ async function runMiddleware(component: string, props: Record<string, unknown> =
     for (const route of manifest().routes as { component: string; middleware?: string[] }[]) {
       if (route.middleware?.length) middlewareChains[route.component] = route.middleware
     }
+
+    // Api routes too. They are keyed by the module name rather than a
+    // component, but the chain above them is the same one the pages beside
+    // them run.
+    for (const api of (manifest().apis ?? []) as { name: string; middleware?: string[] }[]) {
+      if (api.middleware?.length) middlewareChains[api.name] = api.middleware
+    }
   }
 
   for (const name of middlewareChains[component] ?? []) {
@@ -1689,7 +2091,7 @@ export async function handleRscStream(
  * Returning undefined leaves React's own behaviour alone for everything else.
  */
 function flightOnError(error: unknown): string | undefined {
-  const digest = redirectDigest(error)
+  const digest = redirectDigest(error) ?? notFoundDigest(error)
 
   if (digest) return digest
 
@@ -1890,7 +2292,11 @@ export async function handleQuery(
   id: string,
   args: string,
   report?: (error: unknown) => string,
-): Promise<{ stream: ReadableStream; cacheControl: string } | null> {
+): Promise<
+  | { stream: ReadableStream; cacheControl: string }
+  | { status: number; message: string; errors?: Record<string, string[]> }
+  | null
+> {
   applyHost()
 
   let fn: unknown
@@ -1907,7 +2313,22 @@ export async function handleQuery(
   if (!isQuery(fn)) return null
 
   const decoded = (await decodeReply(args)) as unknown[]
-  const result = await (fn as (...a: unknown[]) => unknown)(...decoded)
+
+  // Awaited here rather than handed to the renderer as a promise, so a refusal
+  // is still a status line rather than an error row inside a 200. React strips
+  // a thrown message in production, so a query that rejected mid-stream would
+  // reach the browser as "an error occurred" with the fields gone.
+  let result: unknown
+
+  try {
+    result = await (fn as (...a: unknown[]) => unknown)(...decoded)
+  } catch (error) {
+    if (isQueryValidationError(error)) {
+      return { status: 422, errors: error.errors, message: error.message }
+    }
+
+    return { status: 500, message: report ? report(error) : 'Query failed.' }
+  }
 
   return {
     stream: renderToReadableStream(result, {
@@ -2017,12 +2438,31 @@ export async function resolveMetadata(
     : {}
 
   // Non-title metadata: layout defaults (outer→inner), page overrides.
+  //
+  // other merges per key rather than being replaced, so a page adding one
+  // custom tag keeps the ones its layout set. Assigning it like any other key
+  // would mean a root layout's theme-color disappearing from every page that
+  // happened to declare one of its own.
   const merged: Record<string, unknown> = {}
+  const other: Record<string, unknown> = {}
+
+  const take = (from: Record<string, unknown>) => {
+    for (const [k, v] of Object.entries(from)) {
+      if (k === 'title') continue
+      if (k === 'other') Object.assign(other, v as Record<string, unknown>)
+      else merged[k] = v
+    }
+  }
+
   for (const l of layouts) {
     const s = metadataMap[l.component]?.static
-    if (s) for (const [k, v] of Object.entries(s)) if (k !== 'title') merged[k] = v
+
+    if (s) take(s as Record<string, unknown>)
   }
-  for (const [k, v] of Object.entries(page)) if (k !== 'title') merged[k] = v
+
+  take(page)
+
+  if (Object.keys(other).length > 0) merged.other = other
 
   // Title: the page title with the NEAREST layout title.template applied; if the
   // page has no title, the nearest layout default/string title.
@@ -2052,7 +2492,7 @@ export async function handleRsc(
   pageKey = '',
   bootstrap = true,
   canReachHost = true,
-): Promise<{ body: string; rscPayload: string; clientChunks: unknown; usedDynamicApis: boolean; clientComponents: string[] }> {
+): Promise<{ body: string; rscPayload: string; clientChunks: unknown; usedDynamicApis: boolean; dynamicBecause: string[]; clientComponents: string[] }> {
   applyHost()
 
   // A build renders this with no host installed, so every rpc() has to suspend
@@ -2063,10 +2503,18 @@ export async function handleRsc(
   // Defaults to true because the other caller is an interception, which runs
   // at request time with a real host and must not be probed.
   let usedDynamicApis = false
+  const hostCalls: string[] = []
 
-  const probe = (..._args: unknown[]) => {
+  const probe = (...args: unknown[]) => {
     usedDynamicApis = true
 
+    // The name it was called with, so the build can say rpc("getUser") rather
+    // than "this page reached for the host" and leave you to find which call.
+    const name = typeof args[0] === 'string' ? args[0] : null
+    const said = name ? 'rpc(' + JSON.stringify(name) + ')' : 'rpc()'
+
+    if (!hostCalls.includes(said)) hostCalls.push(said)
+
     return new Promise<never>(() => {})
   }
 
@@ -2382,12 +2830,48 @@ export default async function handler(request: Request): Promise<Response> {
       handleRscResume,
       handleAction,
       handleQuery,
+      handleApiRoute,
       resolveMetadata,
       runRouteMiddleware,
     } as never,
 ${NITRO_HANDLER_OPTIONS}${NITRO_PRERENDERED}  })
 
-${fallbackOrigin ? FALLBACK_BODY : "  return (await devHandler(request)) ?? new Response('Not found', { status: 404 })\n"}}
+${fallbackOrigin ? FALLBACK_BODY : "  return (await devHandler(request)) ?? (await notFound())\n"}}
+
+/**
+ * The page for a url nothing answers.
+ *
+ * Rendered through its layout chain like any other page, so the 404 a visitor
+ * sees is the app rather than a bare string — and returned with a 404, because
+ * a page that says "not found" under a 200 is a page search engines index.
+ *
+ * Without a not-found.tsx this is the string it always was.
+ */
+async function notFound(): Promise<Response> {
+  ${notFoundComponent ? `
+  try {
+    const { htmlStream } = await handleRscHtmlStream(
+      ${JSON.stringify(notFoundComponent)},
+      {},
+      ${JSON.stringify(notFoundLayouts.map((component) => ({ component, props: {} })))},
+      [],
+      {},
+      {},
+      undefined,
+      '/404',
+    )
+
+    return new Response(htmlStream, {
+      status: 404,
+      headers: { 'Content-Type': 'text/html; charset=utf-8' },
+    })
+  } catch {
+    // A 404 page that throws is still a 404. Falling back rather than
+    // answering 500 keeps the status honest about what happened.
+  }
+  ` : ''}
+  return new Response('Not found', { status: 404 })
+}
 `;
 }
 function generateEntrySsr() {
@@ -2668,6 +3152,27 @@ function hasLoadingInChain(pageDir) {
  * blank screen. A page whose slow work lives in children behind their own
  * <Suspense> already paints a shell and needs nothing.
  */
+/**
+ * An `error.tsx` has to be a client component.
+ *
+ * It is rendered inside a React error boundary, which is a class component in
+ * the browser, and it is handed a `reset` callback to call. A server component
+ * can be neither. Caught here rather than at runtime, where the symptom is a
+ * boundary that renders nothing while the error it was written for goes to the
+ * console.
+ */
+function validateErrorBoundaries() {
+    const wrong = [];
+    for (const c of components.values()) {
+        if (!c.name.endsWith('/error'))
+            continue;
+        const source = readFileSync(c.absPath, 'utf-8');
+        if (!/^\s*['"]use client['"]/m.test(source)) {
+            wrong.push(`  ${relative(projectRoot, c.absPath)}`);
+        }
+    }
+    return wrong;
+}
 function validateLoadingBoundaries() {
     const errors = [];
     for (const c of components.values()) {
@@ -2721,6 +3226,13 @@ export function rscKit(options = {}) {
                     throw new Error(`[rsc-kit] ${message}`);
                 log(message);
             }
+            const notClient = validateErrorBoundaries();
+            if (notClient.length) {
+                throw new Error('[rsc-kit] An error.tsx must be a client component.\n\n' +
+                    notClient.join('\n') +
+                    "\n\nAdd 'use client' at the top. It is rendered inside an error boundary and is\n" +
+                    'handed a reset() callback to call, neither of which a server component can do.');
+            }
             const loadingErrors = validateLoadingBoundaries();
             if (loadingErrors.length) {
                 throw new Error('[rsc-kit] A page that blocks before it can paint needs a loading.tsx boundary.\n\n' +
@@ -3032,7 +3544,25 @@ export function rscKit(options = {}) {
     // With Nitro, the server handler is Nitro's — it takes the rsc entry's
     // default export and builds the server around it. Leaving plugin-rsc's own
     // handler in place means two things claiming the same role.
-    return [appPluginRsc({ serverHandler: false }), routesPlugin];
+    return [
+        appPluginRsc({
+            serverHandler: false,
+            // One chunk per client component, rather than one for the whole app.
+            //
+            // plugin-rsc already loads a client reference with `await import()`, so
+            // the browser only fetches what a page actually renders — but its default
+            // groups every reference by the SERVER chunk that proxies it, and this
+            // package builds the server as a single chunk. So every client component
+            // in an app landed in one group, and a page with a button pulled in the
+            // editor, the chart and the map that live on other routes.
+            //
+            // Grouping by the component's own module restores the split the dynamic
+            // import was there to make use of.
+            clientChunks: (meta) => meta.normalizedId,
+            ...actionEncryptionKey(),
+        }),
+        routesPlugin,
+    ];
 }
 /**
  * @vitejs/plugin-rsc, resolved from the app rather than from here.
@@ -3051,6 +3581,36 @@ export function rscKit(options = {}) {
  * Resolving from the project root gets the app's copy, whose own `vite` import
  * then resolves to the app's Vite as well — one pair, and the check passes.
  */
+/**
+ * Where the key that encrypts bound action arguments comes from.
+ *
+ * A server action can close over server-side values, and React sends those to
+ * the browser encrypted so the page cannot read them. The process that decrypts
+ * them on the way back has to hold the same key.
+ *
+ * By default plugin-rsc generates one per build and bakes it in. Every instance
+ * of one build therefore agrees, and the only exposure is a deploy: a browser
+ * holding a page from the old build calls an action on the new one, and the
+ * key has changed underneath it. The call fails with nothing useful in it.
+ *
+ * Setting RSC_ACTION_ENCRYPTION_KEY makes the key outlive the build and closes
+ * that window. It is read at RUNTIME, not baked in, so the same artifact can be
+ * deployed anywhere — but it must then be set everywhere the app runs, and set
+ * to the same value. Half-configured is worse than unconfigured: instances
+ * would disagree, and the failure looks like an intermittently broken action.
+ *
+ * Unset, the build-time key is used and nothing changes. That is the default
+ * because it is the one that cannot be got half right.
+ */
+function actionEncryptionKey() {
+    if (!process.env.RSC_ACTION_ENCRYPTION_KEY)
+        return {};
+    // An expression, not a value: plugin-rsc substitutes this source text where
+    // the key is read, so what ships is the lookup rather than the secret. A
+    // literal here would put the key in the bundle, which is the thing being
+    // avoided.
+    return { defineEncryptionKey: 'process.env.RSC_ACTION_ENCRYPTION_KEY' };
+}
 async function appPluginRsc(options = {}) {
     try {
         // Resolved against a file *in* the root, since a directory specifier