@k8ordo/framework 1.0.0 → 1.1.0

package/README.md

@@ -33,12 +33,13 @@ dependencies in either mode: the build bundles what the application runs.
 
 <!-- peers -->
 
-| Package          | Version | Required | Needed for                                 |
-| ---------------- | ------- | -------- | ------------------------------------------ |
-| `@k8ordo/router` | ^1.0.0  | yes      | routing, re-exported by the framework      |
-| `react`          | ≥19.3.0 | yes      | rendering                                  |
-| `react-dom`      | ≥19.3.0 | yes      | rendering                                  |
-| `vite`           | ≥8.0.0  | yes      | the build (`framework()` is a Vite plugin) |
+| Package               | Version  | Required | Needed for                                 |
+| --------------------- | -------- | -------- | ------------------------------------------ |
+| `@k8ordo/router`      | ^1.1.0   | yes      | routing, re-exported by the framework      |
+| `react`               | ≥19.3.0  | yes      | rendering                                  |
+| `react-dom`           | ≥19.3.0  | yes      | rendering                                  |
+| `vite`                | ≥8.0.0   | yes      | the build (`framework()` is a Vite plugin) |
+| `oxc-transform-react` | ^0.152.0 | optional | `reactCompiler: true` (React Compiler)     |
 
 <!-- /peers -->
 
@@ -134,7 +135,9 @@ A value `paths` does not list — a product added after the build — is
 answered by a `fallback.tsx` beside the page: the build writes it once as a
 shell, the layouts in HTML, and the browser draws the page from the URL.
 The build also writes the `_redirects` through which Netlify and Cloudflare
-reach the shell, and `vercel()` the same rewrites for Vercel.
+reach the shell, and `vercel()` the same rewrites for Vercel — around them,
+routes of your own: headers on every page, redirects, a rewrite decided by
+`Accept`, a proxy to another origin.
 
 ## AI Agent Documentation
 

package/dist/generated.mjs

@@ -1,2 +1 @@
-import { defineRoutes } from "@k8ordo/router";
-export { defineRoutes };
+export { defineRoutes } from "@k8ordo/router";

package/dist/index.mjs

@@ -1,2 +1 @@
-import { bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase } from "@k8ordo/router";
-export { bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase };
+export { bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase } from "@k8ordo/router";

package/dist/runtime/fallback-boundary.d.mts

@@ -39,4 +39,5 @@ export declare class FallbackCatch extends Component<CatchProps, CatchState> {
 export declare const FallbackBoundary: ({ children }: {
   children: ReactNode;
 }) => ReactNode;
-//#endregion
+//#endregion
+export {};

package/dist/runtime/guard.d.mts

@@ -26,4 +26,5 @@ type AnyGuard = (context: {
  * inner guard assume what an outer one checked.
  */
 export declare const runGuards: (guards: readonly AnyGuard[], context: Parameters<AnyGuard>[0]) => Promise<Response | null>;
-//#endregion
+//#endregion
+export {};

package/dist/runtime/page-boundary.d.mts

@@ -36,4 +36,5 @@ export declare class PageBoundary extends Component<{
   componentDidCatch(error: unknown): void;
   render(): ReactNode;
 }
-//#endregion
+//#endregion
+export {};

package/dist/runtime/params.d.mts

@@ -46,4 +46,5 @@ export declare const parseParams: (schemas: readonly ParamsSchema[], raw: Readon
  * says.
  */
 export declare const parseCatchAllParams: (schemas: readonly ParamsSchema[], raw: Readonly<Record<string, string>>) => ParsedParams;
-//#endregion
+//#endregion
+export {};

package/dist/runtime/redirect-file.d.mts

@@ -18,4 +18,5 @@ type ResolvedRedirect = {
  * the table normalizes it, so `/old/` is `/old` here too.
  */
 export declare const resolveRedirects: (declared: Readonly<Record<string, RedirectTarget>>) => ((pattern: string, pathname: string) => ResolvedRedirect | null);
-//#endregion
+//#endregion
+export {};

package/dist/runtime/redirect.d.mts

@@ -25,4 +25,5 @@ export declare class Redirect extends Error {
  */
 export declare const redirect: (to: string) => never;
 export declare const isRedirect: (value: unknown) => value is Redirect;
-//#endregion
+//#endregion
+export {};

package/dist/runtime/route.d.mts

@@ -32,4 +32,5 @@ export declare const methodNotAllowed: (module: AnyRouteModule) => Response;
  * answers the request as much as a guard does.
  */
 export declare const runRoute: ({ handler, headOnly }: RouteAnswer, context: RouteContext) => Promise<Response>;
-//#endregion
+//#endregion
+export {};

package/dist/static-BaGdAVF1.d.mts

@@ -0,0 +1,66 @@
+import { Plugin, PluginOption } from "vite";
+import "react";
+//#region ../framework-engine/dist/host.d.mts
+/** What `framework()` takes whatever the mode. */
+type EngineOptions = {
+  /** Where the route files live, relative to the project root. */
+  readonly routesDir?: string;
+  /**
+   * Compiles the client components with React Compiler — the Rust one,
+   * through `@vitejs/plugin-react`'s `compiler`, which needs
+   * `oxc-transform-react` installed. Server components are left as they are.
+   */
+  readonly reactCompiler?: boolean;
+};
+//#endregion
+//#region src/documents.d.ts
+/**
+ * The `Content-Security-Policy` an application wants on every page, as
+ * directives and their sources. The build writes it into each page's
+ * `<meta>`, with the hashes of that page's signed inline scripts added.
+ */
+type ContentSecurityPolicy = Readonly<Record<string, readonly string[]>>;
+//#endregion
+//#region src/static.d.ts
+type StaticOptions = EngineOptions & {
+  /**
+   * Every route rendered at build time and written to files; no server at
+   * run time, so nothing that answers a request (Server Actions, guards, the
+   * request API) builds.
+   */
+  readonly mode: 'static';
+  /**
+   * Pathnames for routes with parameters, in the table's terms — without
+   * Vite's `base`. Static rendering cannot invent them, and a build that
+   * quietly skipped half the site would be worse than one that refuses.
+   *
+   * The patterns that need covering are handed in, so a site whose parameter
+   * takes the same values everywhere — a locale segment, say — expands them
+   * rather than listing every page twice.
+   *
+   * For a page with a `fallback.tsx` beside it, a pathname that still holds
+   * a parameter (`/ja/posts/:id`) is where its shell stands: the values the
+   * build did not write are answered there. Without one, the bare pattern
+   * is the shell's location.
+   */
+  readonly paths?: (patterns: readonly string[]) => readonly string[] | Promise<readonly string[]>;
+  /**
+   * The origin the site is served from — `https://example.com`. With it the
+   * build also writes `sitemap.xml`, listing every page it rendered at its
+   * URL, Vite's `base` included; without it, no sitemap, because a sitemap of
+   * relative URLs is not one.
+   */
+  readonly site?: string;
+  /**
+   * The `Content-Security-Policy` every page carries, as directives and
+   * their sources. The framework decides no policy: it writes this one into
+   * each page's `<meta>`, adding to `script-src` the hashes of its own inline
+   * scripts on that page — the payload and React's. An inline script of the
+   * application's is allowed by its hash here, as
+   * `colorSchemeScriptHash()` gives `@k8ordo/color-scheme`'s. Without it, no
+   * policy is written.
+   */
+  readonly csp?: ContentSecurityPolicy;
+};
+//#endregion
+export { ContentSecurityPolicy as n, EngineOptions as r, StaticOptions as t };

package/dist/vercel.d.mts

@@ -1,4 +1,46 @@
+import "./static-BaGdAVF1.mjs";
 import { Plugin } from "vite";
+//#region src/vercel-output.d.ts
+/**
+ * A route as Vercel's Build Output API (v3) reads it, written to
+ * `.vercel/output/config.json` as given — the fields an application needs.
+ */
+type VercelRoute = {
+  /**
+   * A regular expression Vercel matches against the whole pathname, the
+   * query left out — `^/posts/` does not match `/posts/first`, `^/posts/.+$`
+   * does — regardless of case unless `caseSensitive`.
+   */
+  readonly src: string;
+  /** A path in the deployment, or a URL elsewhere. */
+  readonly dest?: string;
+  readonly status?: number;
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Keep matching the routes after this one: a route that only adds headers. */
+  readonly continue?: boolean;
+  /**
+   * Look for `dest` among the files; when none is there, go on with `dest`
+   * as the pathname.
+   */
+  readonly check?: boolean;
+  readonly caseSensitive?: boolean;
+  readonly has?: ReadonlyArray<{
+    readonly type: 'header';
+    /** Lowercase, as Vercel compares it. */
+    readonly key: string;
+    readonly value?: string;
+  }>;
+};
+type VercelOptions = {
+  /** Under `mode: 'static'`, routes tried before any file. */
+  readonly beforeFiles?: readonly VercelRoute[];
+  /**
+   * Under `mode: 'static'`, routes tried once neither a file nor a shell
+   * answered, before `404.html`.
+   */
+  readonly beforeNotFound?: readonly VercelRoute[];
+};
+//#endregion
 //#region src/vercel.d.ts
 /**
  * Deploys the application to Vercel: after `vite build`, the build is also
@@ -9,7 +51,11 @@ import { Plugin } from "vite";
  * nothing but its own directory, which is all the handler needs: server mode
  * builds it with every dependency bundled in. Under `mode: 'static'` there is
  * no function, only the rewrites that answer a value the build did not write
- * with its shell — Vercel never reads `_redirects`.
+ * with its shell — Vercel never reads `_redirects` — and the application's
+ * own routes around them, written as given: `beforeFiles` ahead of every
+ * file, `beforeNotFound` ahead of `404.html`. A file a `route.ts` wrote is
+ * served with the `Content-Type` its `GET` answered.
  */
-export declare const vercel: () => Plugin;
-//#endregion
+export declare const vercel: (options?: VercelOptions) => Plugin;
+//#endregion
+export type { VercelOptions, VercelRoute };

package/dist/vercel.mjs

@@ -7,12 +7,17 @@ import path from "node:path";
 const FUNCTION = "handler";
 /**
 * The hashed assets are marked immutable in the `hit` phase — only once a
-* file answered — so a missing one is never cached for a year.
+* file answered — so a missing one is never cached for a year. `src` spells
+* out the rest of the path, since Vercel matches it against the whole path
+* and a prefix alone matches no file; `important`, as `@vercel/next` marks
+* its own hashed files, keeps another route's `Cache-Control` from taking
+* its place.
 */
 const immutableAssets = (base) => ({
-	src: `^${RegExp.escape(`${base}assets/`)}`,
+	src: `^${RegExp.escape(`${base}assets/`)}.+$`,
 	headers: { "cache-control": "public, max-age=31536000, immutable" },
-	continue: true
+	continue: true,
+	important: true
 });
 /** Files first, and whatever names none goes to the handler. */
 const configFor = (base) => ({
@@ -57,15 +62,21 @@ const routeOf = (rule) => {
 	};
 };
 /**
-* Files first; only what names none is rewritten — a value the build did
-* not write to its shell, the payload URL of a built URL that is not a page
-* to HTML — and what nothing rewrote is the build's `404.html`.
+* The application's `beforeFiles`, then the files; only what names none is
+* rewritten — a value the build did not write to its shell, the payload URL
+* of a built URL that is not a page to HTML — and what nothing rewrote goes
+* through the application's `beforeNotFound` to the build's `404.html`. A
+* file a route.ts wrote is served with the type its `GET` answered, even
+* where the extension says the same, so no file is left to the types Vercel
+* gives an extension.
 */
-const staticConfigFor = ({ base, rewrites, notFound }) => ({
+const staticConfigFor = ({ base, rewrites, notFound, types }, { beforeFiles = [], beforeNotFound = [] }) => ({
 	version: 3,
 	routes: [
+		...beforeFiles,
 		{ handle: "filesystem" },
 		...rewrites.map((rule) => routeOf(rule)),
+		...beforeNotFound,
 		...notFound ? [{
 			src: "^/.*$",
 			dest: withBase("/404.html", base),
@@ -73,7 +84,8 @@ const staticConfigFor = ({ base, rewrites, notFound }) => ({
 		}] : [],
 		{ handle: "hit" },
 		immutableAssets(base)
-	]
+	],
+	...types.size === 0 ? {} : { overrides: Object.fromEntries([...types].toSorted(([a], [b]) => a < b ? -1 : 1).map(([file, contentType]) => [withBase(`/${file}`, base).slice(1), { contentType }])) }
 });
 /**
 * A Node.js function that hands Vercel the handler as it is: the launcher
@@ -129,10 +141,11 @@ const writeVercelOutput = async (root, dirs, base) => {
 /**
 * A static build laid out as Vercel's Build Output API (v3) reads it: the
 * client build as static files at Vite's `base`, and the rewrites a host
-* applies once no file answered as routes — no function. `_redirects` stays
-* behind: Vercel never reads it, and would serve it as a file.
+* applies once no file answered as routes, around them the application's
+* own — no function. `_redirects` stays behind: Vercel never reads it, and
+* would serve it as a file.
 */
-const writeStaticVercelOutput = async (output) => {
+const writeStaticVercelOutput = async (output, routes = {}) => {
 	const dir = path.join(output.root, ".vercel", "output");
 	await rm(dir, {
 		recursive: true,
@@ -143,7 +156,7 @@ const writeStaticVercelOutput = async (output) => {
 		recursive: true,
 		filter: (source) => source !== redirects
 	});
-	await writeFile(path.join(dir, "config.json"), json(staticConfigFor(output)));
+	await writeFile(path.join(dir, "config.json"), json(staticConfigFor(output, routes)));
 };
 //#endregion
 //#region src/vercel.ts
@@ -156,9 +169,14 @@ const writeStaticVercelOutput = async (output) => {
 * nothing but its own directory, which is all the handler needs: server mode
 * builds it with every dependency bundled in. Under `mode: 'static'` there is
 * no function, only the rewrites that answer a value the build did not write
-* with its shell — Vercel never reads `_redirects`.
+* with its shell — Vercel never reads `_redirects` — and the application's
+* own routes around them, written as given: `beforeFiles` ahead of every
+* file, `beforeNotFound` ahead of `404.html`. A file a `route.ts` wrote is
+* served with the `Content-Type` its `GET` answered.
 */
-const vercel = () => {
+const vercel = (options = {}) => {
+	const { beforeFiles, beforeNotFound } = options;
+	for (const route of [...beforeFiles ?? [], ...beforeNotFound ?? []]) for (const { key } of route.has ?? []) if (key !== key.toLowerCase()) throw new Error(`vercel() route ${route.src} has the header key "${key}" — write it lowercase ("${key.toLowerCase()}"), as Vercel compares it`);
 	let isStatic = false;
 	let logger;
 	return {
@@ -167,9 +185,10 @@ const vercel = () => {
 		configResolved(config) {
 			isStatic = config.plugins.some((plugin) => plugin.name === "k8ordo:static");
 			({logger} = config);
+			if (!isStatic && (beforeFiles !== void 0 || beforeNotFound !== void 0)) throw new Error("vercel() takes beforeFiles and beforeNotFound under mode: 'static' only — under mode: 'server' the handler answers every URL no file names");
 		},
 		api: { async writeStatic(output) {
-			await writeStaticVercelOutput(output);
+			await writeStaticVercelOutput(output, options);
 			logger?.info("k8ordo: wrote .vercel/output");
 		} },
 		buildApp: {

package/dist/vite.d.mts

@@ -1,62 +1,5 @@
-import { Plugin, PluginOption } from "vite";
-import "react";
-//#region ../framework-engine/dist/host.d.mts
-/** What `framework()` takes whatever the mode. */
-type EngineOptions = {
-  /** Where the route files live, relative to the project root. */
-  readonly routesDir?: string;
-};
-//#endregion
-//#region src/documents.d.ts
-/**
- * The `Content-Security-Policy` an application wants on every page, as
- * directives and their sources. The build writes it into each page's
- * `<meta>`, with the hashes of that page's signed inline scripts added.
- */
-type ContentSecurityPolicy = Readonly<Record<string, readonly string[]>>;
-//#endregion
-//#region src/static.d.ts
-type StaticOptions = EngineOptions & {
-  /**
-   * Every route rendered at build time and written to files; no server at
-   * run time, so nothing that answers a request (Server Actions, guards, the
-   * request API) builds.
-   */
-  readonly mode: 'static';
-  /**
-   * Pathnames for routes with parameters, in the table's terms — without
-   * Vite's `base`. Static rendering cannot invent them, and a build that
-   * quietly skipped half the site would be worse than one that refuses.
-   *
-   * The patterns that need covering are handed in, so a site whose parameter
-   * takes the same values everywhere — a locale segment, say — expands them
-   * rather than listing every page twice.
-   *
-   * For a page with a `fallback.tsx` beside it, a pathname that still holds
-   * a parameter (`/ja/posts/:id`) is where its shell stands: the values the
-   * build did not write are answered there. Without one, the bare pattern
-   * is the shell's location.
-   */
-  readonly paths?: (patterns: readonly string[]) => readonly string[] | Promise<readonly string[]>;
-  /**
-   * The origin the site is served from — `https://example.com`. With it the
-   * build also writes `sitemap.xml`, listing every page it rendered at its
-   * URL, Vite's `base` included; without it, no sitemap, because a sitemap of
-   * relative URLs is not one.
-   */
-  readonly site?: string;
-  /**
-   * The `Content-Security-Policy` every page carries, as directives and
-   * their sources. The framework decides no policy: it writes this one into
-   * each page's `<meta>`, adding to `script-src` the hashes of its own inline
-   * scripts on that page — the payload and React's. An inline script of the
-   * application's is allowed by its hash here, as
-   * `colorSchemeScriptHash()` gives `@k8ordo/color-scheme`'s. Without it, no
-   * policy is written.
-   */
-  readonly csp?: ContentSecurityPolicy;
-};
-//#endregion
+import { n as ContentSecurityPolicy, r as EngineOptions, t as StaticOptions } from "./static-BaGdAVF1.mjs";
+import { PluginOption } from "vite";
 //#region src/vite.d.ts
 export type ServerOptions = EngineOptions & {
   /**

package/dist/vite.mjs

@@ -1079,7 +1079,7 @@ const engine = (options, host) => {
 		mode: host.mode
 	});
 	return [
-		react(),
+		react({ compiler: options.reactCompiler === true }),
 		rsc(),
 		{
 			name: "k8ordo:engine",
@@ -1351,10 +1351,12 @@ const redirectPage = (to) => {
 	const escaped = escapeMarkup(to);
 	return `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${escaped}"><link rel="canonical" href="${escaped}"><title>Redirecting</title></head><body><a href="${escaped}">${escaped}</a></body></html>\n`;
 };
-const HEADER_ONLY = /* @__PURE__ */ new Set([
-	"frame-ancestors",
-	"report-uri",
-	"sandbox"
+const IGNORED = "is ignored in a <meta> — set it as a header at the host";
+const HEADER_ONLY = /* @__PURE__ */ new Map([
+	["frame-ancestors", IGNORED],
+	["report-uri", IGNORED],
+	["sandbox", IGNORED],
+	["report-to", "names an endpoint only a Reporting-Endpoints response header defines — set the policy as a header at the host"]
 ]);
 /** What decides scripts: `script-src`, or `default-src` without it. */
 const scriptDirectiveOf = (policy) => {
@@ -1374,15 +1376,16 @@ const elementDirectivesOf = (policy) => {
 };
 /**
 * What would make a policy wrong to write into every page, named at once:
-* a directive a `<meta>` ignores, a source that is not one, and
+* a directive that works only from a header, a source that is not one, and
 * `'strict-dynamic'`, under which the framework's module script — allowed by
 * where it comes from, since a file cannot sign it — would never load.
 */
 const policyProblems = (policy) => {
 	const problems = [];
 	for (const [name, sources] of Object.entries(policy)) {
+		const headerOnly = HEADER_ONLY.get(name);
 		if (!/^[a-z][a-z-]*$/u.test(name)) problems.push(`"${name}" is not a directive name`);
-		else if (HEADER_ONLY.has(name)) problems.push(`${name} is ignored in a <meta> — set it as a header at the host`);
+		else if (headerOnly !== void 0) problems.push(`${name} ${headerOnly}`);
 		for (const source of sources) if (source === "" || /[\s;,]/u.test(source)) problems.push(`"${source}" in ${name} is not one source — give each its own entry`);
 	}
 	for (const [name, sources] of elementDirectivesOf(policy)) if (sources.includes("'strict-dynamic'")) problems.push(`'strict-dynamic' in ${name} would block the framework's module script, which a file allows by where it comes from ('self'), not by a hash`);
@@ -2085,10 +2088,13 @@ const staticMode = (options) => {
 				const failed = [];
 				const redirected = /* @__PURE__ */ new Set();
 				const unanswered = [];
+				const types = /* @__PURE__ */ new Map();
 				await inParallel(plan.paths.flatMap((pathname) => {
 					if (byRoute.has(pathname)) return [async () => {
-						const status = await writeRoute(path.join(clientDir, dirFor(pathname)), handler, urlFor(pathname));
+						const file = path.join(clientDir, dirFor(pathname));
+						const { status, type } = await writeRoute(file, handler, urlFor(pathname));
 						if (status !== 200) unanswered.push(`${pathname} (${String(status)})`);
+						else if (type !== null) types.set(path.relative(clientDir, file).split(path.sep).join("/"), type);
 					}];
 					const dir = path.join(clientDir, dirFor(pathname));
 					return [async () => {
@@ -2153,7 +2159,8 @@ const staticMode = (options) => {
 					client: clientDir,
 					base,
 					rewrites,
-					notFound: unmatched !== null
+					notFound: unmatched !== null,
+					types
 				});
 				else if (vercel === void 0 && process.env.VERCEL !== void 0 && plan.shells.length > 0) builder.config.logger.warn("k8ordo: this build runs on Vercel, which does not read _redirects — add vercel() from @k8ordo/framework/vercel, or the shells are never served");
 				const shells = plan.shells.length === 0 ? "" : `, ${String(plan.shells.length)} ${plan.shells.length === 1 ? "shell" : "shells"} (${plan.shells.map((shell) => shell.location).join(", ")})`;
@@ -2209,19 +2216,27 @@ const write = async (file, handler, url, csp, { notFoundIsPage, shell }) => {
 	return written;
 };
 /**
-* Writes what a route.ts's GET answered, as the file at its pathname — a
-* static host then serves it with the type its extension says. Anything but a
-* 200 is not a file the site has, and nothing is written.
+* Writes what a route.ts's GET answered, as the file at its pathname, and
+* says the type it answered with — a file keeps none, so a static host serves
+* it with the type its extension says, and only an adapter that can name a
+* file's type (`vercel()`) serves the GET's. Anything but a 200 is not a file
+* the site has, and nothing is written.
 */
 const writeRoute = async (file, handler, url) => {
 	const response = await handler(new Request(url));
 	if (response.status !== 200) {
 		if (response.status === 500) console.error(`k8ordo: ${url} — ${await response.text()}`);
-		return response.status;
+		return {
+			status: response.status,
+			type: null
+		};
 	}
 	await mkdir(path.dirname(file), { recursive: true });
 	await writeFile(file, Buffer.from(await response.arrayBuffer()));
-	return response.status;
+	return {
+		status: response.status,
+		type: response.headers.get("content-type")
+	};
 };
 //#endregion
 //#region src/vite.ts

package/docs/GUIDE.md

@@ -234,7 +234,9 @@ The package is split by where the code runs.
   `dist/server.js` runs, for a server of your own to import. A static build
   it serves as a static host does, its `_redirects` applied.
 - `@k8ordo/framework/vercel` — `vercel()`, the plugin that writes a build
-  of either mode for Vercel.
+  of either mode for Vercel, and the types `VercelOptions` and
+  `VercelRoute`. Under static mode it also takes routes of your own,
+  `beforeFiles` and `beforeNotFound`.
 - `@k8ordo/framework/generated` — what the generated `.k8ordo/` files
   import. Not for code written by hand.
 
@@ -245,10 +247,22 @@ dev dependencies.
 
 ## The options
 
-`framework()` takes `mode`, which is required, and `routesDir`, the route
-directory (default `src/routes`). Three more describe files, so only
-`mode: 'static'` takes them — passing them with `mode: 'server'` is a type
-error:
+`framework()` takes `mode`, which is required, `routesDir`, the route
+directory (default `src/routes`), and `reactCompiler`, in either mode.
+
+`reactCompiler: true` compiles the client components with React Compiler —
+the Rust one, `oxc-transform-react`, through `@vitejs/plugin-react`'s
+`compiler` — in `vite dev` and in the build. Install it beside the framework
+as a dev dependency, in the range the package's README gives under Peer
+Dependencies. Without it, `vite dev` and `vite build` stop as soon as they
+read the config, with React's plugin's own error
+(`React Compiler requires the optional …`), which names
+`react({ compiler: true })`: the option the framework sets for you. Only
+what runs in the browser is compiled; Server Components, and the HTML a
+client component renders on the server, are left as written.
+
+Three more describe files, so only `mode: 'static'` takes them — passing
+them with `mode: 'server'` is a type error:
 
 - `paths` — the pathnames of routes with parameters, and where a
   `fallback.tsx`'s shell stands

package/docs/llms.txt

@@ -52,7 +52,9 @@ Start with GUIDE.md, then follow the reference most relevant to the task.
 - [Design Guide](GUIDE.md): choosing a mode and what static mode refuses,
   setup (install, `vite.config.ts`, `tsconfig.json`, the root layout as the
   document), `vite dev` and `vite preview` against a static build, the
-  entries, and the plugin's options.
+  entries, and the plugin's options — `reactCompiler` among them, React
+  Compiler on the client components, which needs `oxc-transform-react`
+  installed.
 
 ## References
 
@@ -103,7 +105,8 @@ Start with GUIDE.md, then follow the reference most relevant to the task.
   `node dist/server.js` (`PORT`, `HOST`, every dependency bundled in, and
   `resolve.external` for one that cannot be), `serve` (compression, `ETag`,
   `Range`), the request handler under Node.js, Bun, Deno and Cloudflare
-  Workers, the same-origin rule for a `POST`, and `vercel()` in either mode;
+  Workers, the same-origin rule for a `POST`, and `vercel()` in either mode,
+  with routes of your own under static mode;
   a tab opened before a deploy, and Vite's `base`.
 
 ## Entry points
@@ -130,7 +133,7 @@ Start with GUIDE.md, then follow the reference most relevant to the task.
   `<head>`, with the hashes of the framework's own inline scripts on that
   page added to `script-src` (or `default-src` made into it) and
   `script-src-elem`; a policy with `'strict-dynamic'`, `frame-ancestors`,
-  `report-uri` or `sandbox` is refused. `FrameworkOptions` is
+  `report-uri`, `report-to` or `sandbox` is refused. `FrameworkOptions` is
   `StaticOptions | ServerOptions`. This entry loads Vite and is for
   `vite.config.ts` only.
 - `@k8ordo/framework/server` — server mode only; a static build refuses any
@@ -179,7 +182,15 @@ Start with GUIDE.md, then follow the reference most relevant to the task.
   `.vercel/output/` (Build Output API v3) for `vercel build` /
   `vercel deploy --prebuilt` — the client build as static files at Vite's
   `base` (`assets/` immutable), and under server mode the request handler
-  as one streaming Node.js function; under static mode no function, and the
-  shells' rewrites as routes tried after the files, then `404.html`.
+  as one streaming Node.js function; under static mode no function, the
+  shells' rewrites as routes tried after the files, then `404.html`, and
+  each file a `route.ts` wrote served with the `Content-Type` its `GET`
+  answered (`overrides`) where other hosts go by its extension.
+  Under static mode `vercel({ beforeFiles, beforeNotFound })` also takes
+  routes of the application's own (`VercelRoute`: `src`, `dest`, `status`,
+  `headers`, `continue`, `check`, `caseSensitive`, `has`), written as given
+  before the files and before `404.html`; Vercel alone applies them,
+  matching `src` against the whole pathname (`^/posts/.+$`, not
+  `^/posts/`).
 - `@k8ordo/framework/generated` — what the generated `.k8ordo/` files
   import (`defineRoutes`, `Register`, …). Not for code written by hand.

package/docs/references/csp.md

@@ -91,9 +91,18 @@ page — one that reached it from content — is refused. The framework's module
 script is allowed by where it comes from (`'self'`), since nothing in a file
 can sign it, which is why the build refuses a policy with `'strict-dynamic'`.
 It refuses `frame-ancestors`, `report-uri` and `sandbox` too, which a
-`<meta>` ignores: set those as headers at the host. Without `csp`, no policy
-is written. There is no `nonce()` for this mode: what an application signed
-with it would land in the file, and make every build differ.
+`<meta>` ignores: set those as headers at the host. It refuses `report-to`
+as well: the endpoint it names is defined only by a `Reporting-Endpoints`
+response header, so set a policy that reports as a header at the host.
+That header cannot carry the hashes the build adds page by page, and a
+script runs only where every policy allows it: wherever the header decides
+a script element — `script-src` (`default-src` without it) and
+`script-src-elem` — allow `'self'` and `'unsafe-inline'` with no hash or
+nonce beside them (either turns `'unsafe-inline'` off), and keep `csp`,
+without `report-to`, for the `<meta>`, which allows inline scripts only by
+hash. Without `csp`, no policy is written. There is no `nonce()` for this
+mode: what an application signed with it would land in the file, and make
+every build differ.
 
 A `fallback.tsx`'s shell draws its page in the browser from data the
 browser fetches

package/docs/references/deploy.md

@@ -505,6 +505,163 @@ case-sensitively, as the route table matches; then `404.html` under a `404`,
 when the build wrote one. `vercel()` writes them once the last page is
 written, whichever side of `framework()` it sits.
 
+**A file a `route.ts` wrote is served with the type its `GET` answered**,
+the `Content-Type` `vite dev` sends, written as that file's entry in the
+`overrides` of `config.json`: a feed at `blog/feed` is
+`application/rss+xml`, not the `application/octet-stream` of a file with no
+extension. The type is written even where the extension says the same, so
+no file is left to the type Vercel gives an extension; only a `GET` that
+named none — a body of bytes with no `Content-Type` — leaves its file to it.
+`vite preview` and `serve` still go by the extension
+([A route.ts under static mode](routing.md#under-static-mode)).
+
+### Routes of your own
+
+Under `mode: 'static'`, `vercel()` also takes routes of the application's
+own, in the language Vercel's Build Output API reads — `src`, a regular
+expression for the pathname, with `dest`, `status`, `headers`, `continue`,
+`check`, `caseSensitive` and `has` — and writes them into
+`.vercel/output/config.json` as given, in two places among its own:
+
+```text
+...beforeFiles
+{ handle: 'filesystem' }        the files
+...the shells' rewrites
+...beforeNotFound
+404.html under a 404            when the build wrote one
+{ handle: 'hit' }
+assets/ sent immutable
+```
+
+`beforeFiles` is tried before any file, so it is where headers for every
+answer go, and a redirect or a rewrite that has to win over a file that is
+there. `beforeNotFound` is tried once neither a file nor a shell answered,
+so a catch-all of yours there never hides a shell: it is where a URL the
+build wrote nothing for is proxied to another origin, or answered with a 404
+of another body.
+
+```ts
+// vite.config.ts
+import { vercel } from '@k8ordo/framework/vercel';
+import { framework } from '@k8ordo/framework/vite';
+import { defineConfig } from 'vite';
+
+const acceptsMarkdown = [
+  { type: 'header', key: 'accept', value: '.*text/markdown.*' },
+] as const;
+
+export default defineConfig({
+  plugins: [
+    framework({ mode: 'static' }),
+    vercel({
+      beforeFiles: [
+        {
+          src: '^/.*$',
+          headers: { 'X-Content-Type-Options': 'nosniff' },
+          continue: true,
+        },
+        {
+          src: '^/((?:[^/]+/)*[^/]+)/$',
+          status: 308,
+          headers: { Location: '/$1' },
+        },
+        {
+          src: '^/posts/([a-z0-9-]+)$',
+          has: acceptsMarkdown,
+          dest: '/posts/$1/article.md',
+          check: true,
+          caseSensitive: true,
+        },
+        {
+          src: '^/feed$',
+          headers: { 'Vercel-CDN-Cache-Control': 'max-age=3600' },
+          continue: true,
+          caseSensitive: true,
+        },
+      ],
+      beforeNotFound: [
+        {
+          src: '^/feed$',
+          dest: 'https://api.example.com/feed',
+          caseSensitive: true,
+        },
+        {
+          src: '^/.*$',
+          has: acceptsMarkdown,
+          dest: '/not-found.md',
+          status: 404,
+        },
+      ],
+    }),
+  ],
+});
+```
+
+- A route that only adds headers says `continue: true`, and comes before
+  the route that answers: an answering route ends the matching. What
+  `beforeFiles` adds this way is on every answer the routes lead to — a
+  file, a redirect, `404.html`, a `dest` with a `status`, an answer proxied
+  from another origin.
+- The redirect takes the trailing slash off and keeps the query:
+  `/about/?x=1` goes to `/about?x=1`, which Vercel answers from
+  `about/index.html` as it is. Its pattern takes no empty segment, so it
+  never answers with `Location: //evil.test`, which a browser reads as
+  another origin. Vercel itself answers `//evil.test/` before any route, with
+  a 308 to `/evil.test/` that carries none of your headers.
+- `check: true` looks for `dest` among the files. When none is there, the
+  matching goes on with `dest` as the pathname: `beforeNotFound` sees
+  `/posts/nope/article.md`, not `/posts/nope`. Here a `route.ts` at
+  `routes/posts/[slug]/article.md/` wrote each post's markdown beside its
+  page, and a client asking for markdown is answered with it. Have `paths`
+  give the pages and their markdown from one list of posts, so no post is
+  written without the other.
+- `has` matches the header's text against `value`, a regular expression,
+  and negotiates nothing: `.*text/markdown.*` takes
+  `Accept: text/markdown, text/html;q=0.9`, and not a browser's
+  `text/html,application/xhtml+xml,*/*;q=0.8`, though `*/*` would take
+  markdown.
+- A proxy is two routes: its headers ahead of the files, and the `dest` that
+  answers after them. The `dest` is asked with the request's query:
+  `/feed?page=2` fetches `https://api.example.com/feed?page=2`.
+- `dest` with `status` answers with that file under that status, as the
+  build's own `404.html` route does.
+
+What to keep in mind:
+
+- **`src` matches the whole pathname**, never just its start, and never the
+  query: `^/posts/` does not match `/posts/first`, and `^/posts/.+$` does.
+- **Only Vercel applies them.** `vite dev`, `vite preview` and `serve`
+  answer as if they were not there — no header, no redirect, nothing decided
+  by `Accept` — since an imitation of Vercel's routing that differed from it
+  would pass locally and fail once deployed. A URL only a route of yours
+  answers is a 404 there.
+- **No `Cache-Control` in a route every path takes.** It reaches every file
+  too, those under `assets/` among them, which `vercel()` marks `immutable`
+  in the `hit` phase, after yours. Give a `Cache-Control` a `src` that names
+  the paths it is for.
+- **Vercel matches `src` regardless of case** unless the route says
+  `caseSensitive: true`, while the routes `vercel()` writes itself are
+  case-sensitive, as the route table is. A route without it answers
+  `/POSTS/first` as well.
+- **`has` names a header in lowercase**, as Vercel compares it. `vercel()`
+  refuses another spelling when it is called:
+
+  ```text
+  vercel() route ^/posts/([a-z0-9-]+)$ has the header key "Accept" — write it lowercase ("accept"), as Vercel compares it
+  ```
+
+- **Nothing else is checked.** The routes are written as given — under a
+  `base` their `src` and `dest` carry it — and their patterns are Vercel's
+  (PCRE), which JavaScript's `RegExp` would misjudge, so a mistake shows once
+  deployed. Try a change on a preview deployment first.
+- **Static mode only.** Under `mode: 'server'` the request handler answers
+  every URL no file names, and a `guard.ts` or a `route.ts` decides what it
+  sends. The build refuses them there:
+
+  ```text
+  vercel() takes beforeFiles and beforeNotFound under mode: 'static' only — under mode: 'server' the handler answers every URL no file names
+  ```
+
 ## A tab opened before a deploy
 
 A tab keeps running the script it loaded, while every payload it fetches

package/docs/references/routing.md

@@ -280,10 +280,14 @@ with params needs `paths`, as a page's does
 ([Parameters](params.md#routes-with-parameters)) — with a request whose
 origin is `site` when that option is given (an RSS feed's links are
 absolute), and writes what it answered as the file at that pathname:
-`dist/client/feed.xml`. A static host then serves it with the type its
-extension says. The `GET` has to answer `200`; anything else stops the build
-naming the pathname. A file answers nothing but `GET`, so a `route.ts`
-exporting another method is refused by name, in the build and in `vite dev`:
+`dist/client/feed.xml`. A file keeps no type of its own, so a static host
+serves it with the type its extension says — `vite preview` and `serve` too,
+which send a file with no extension as `application/octet-stream`. On
+Vercel, `vercel()` serves it with the `Content-Type` its `GET` answered, the
+type `vite dev` sends ([Deploying to Vercel](deploy.md#deploying-to-vercel)).
+The `GET` has to answer `200`; anything else stops the build naming the
+pathname. A file answers nothing but `GET`, so a `route.ts` exporting
+another method is refused by name, in the build and in `vite dev`:
 
 ```
 static build writes a route.ts as the file its GET answers, and a file cannot answer another method — these export one:
@@ -299,6 +303,11 @@ A `route.ts` at `/` cannot be a file (the host serves `/` from `index.html`),
 nor one with pages written below it, which would need a directory of the same
 name. What it writes is not a page, so `sitemap.xml` leaves it out.
 
+Name the type in the `Response`. A string body with none is sent as
+`text/plain;charset=UTF-8` — the `Response` sets it — so a `sitemap.xml`
+returned that way is plain text on Vercel and in `vite dev`, whatever its
+extension says. `vite dev` shows it before a deploy does.
+
 ## The generated files
 
 The framework writes `.k8ordo/` and keeps it in step with the directories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/framework",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The k8ordo framework: routes/ compiled into React Server Components, run with or without a server.",
   "keywords": [
     "k8ordo",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@vitejs/plugin-react": "6.1.2",
-    "@vitejs/plugin-rsc": "0.5.36",
+    "@vitejs/plugin-rsc": "0.5.38",
     "compressible": "2.0.18",
     "fresh": "2.0.0",
     "mime-types": "3.0.2",
@@ -73,26 +73,33 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
     "@k8ordo/framework-engine": "^0.1.1",
-    "@k8ordo/router": "^1.0.0",
+    "@k8ordo/router": "^1.1.0",
     "@types/compressible": "2.0.3",
     "@types/fresh": "0.5.3",
     "@types/mime-types": "3.0.1",
     "@types/range-parser": "1.2.7",
     "@types/react": "19.3.0",
+    "oxc-transform-react": "0.154.0",
     "publint": "0.3.25",
-    "react": "19.3.0",
-    "react-dom": "19.3.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0",
-    "vitest": "5.0.3"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0",
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "@k8ordo/router": "^1.0.0",
+    "@k8ordo/router": "^1.1.0",
+    "oxc-transform-react": "^0.152.0",
     "react": ">=19.3.0",
     "react-dom": ">=19.3.0",
     "vite": ">=8.0.0"
   },
+  "peerDependenciesMeta": {
+    "oxc-transform-react": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=24.0.0"
   },