@k8ordo/framework 0.1.0 → 1.1.0

package/dist/vite.mjs

@@ -1,5 +1,6 @@
 import { _ as pagePathFor, a as cloudflareCounts, b as NOT_FOUND_SEGMENT, c as rewriteFor, d as ENCODINGS, f as SUFFIX, g as isPayloadPath, i as builtRules, l as rulesOf, n as resolveStatic, o as cloudflareMatches, p as isCompressible, s as formatRedirects, t as readRules, u as shellRules, v as payloadPathFor, x as decodePathname, y as FALLBACK_SEGMENT } from "./static-host-dgtttTuZ.mjs";
 import { t as sharedDir } from "./shared-dir-CkF4QCWc.mjs";
+import { findPackageJSON } from "node:module";
 import { normalizePathname, withBase, withoutBase } from "@k8ordo/router";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
@@ -412,7 +413,10 @@ const ANSWERED = "answered";
 */
 const GENERATED_FROM = `${FRAMEWORK}/generated`;
 const ROUTE_REQUEST_FROM = `${FRAMEWORK}/server`;
-const BANNER = `// Generated by ${FRAMEWORK} from routes/. Do not edit.`;
+const I18N = "@k8ordo/i18n";
+/** Where an application declares its locale set, from its root. */
+const LOCALES_MODULE = "src/i18n.ts";
+const bannerFrom = (...sources) => `// Generated by ${FRAMEWORK} from ${sources.join(" and ")}. Do not edit.`;
 const sanitize = (path) => {
 	const base = path.replace(/\.[jt]sx?$/u, "").replaceAll(/[^A-Za-z0-9]+/gu, "_").replaceAll(/^_+|_+$/gu, "");
 	return base === "" ? "route" : base;
@@ -610,7 +614,7 @@ const emitRoutesModule = (tree, options) => {
 		"ParsedParams"
 	];
 	return [
-		BANNER,
+		bannerFrom("routes/"),
 		"",
 		`import { defineRoutes } from '${GENERATED_FROM}';`,
 		...searchReaders.length > 0 ? [`import { urlReader } from '@k8ordo/state';`] : [],
@@ -777,17 +781,22 @@ const namerFile = (namer, name) => {
 * Both packages read the app's route table through declaration merging, so
 * the app gets typed paths everywhere without writing the ceremony itself.
 * The router's `Register` is augmented through the framework's re-export of
-* it, which TypeScript merges into the router's own declaration.
+* it, which TypeScript merges into the router's own declaration. The locale
+* set reaches `@k8ordo/i18n`'s `Register` the same way, so every message is
+* held to it.
 */
 const emitRegisterModule = (options) => {
 	const wantsState = options.stateModule !== null && options.stateModule !== void 0;
+	const localesModule = options.localesModule ?? null;
 	const withRequest = options.mode === "server";
 	const lines = [
-		BANNER,
+		localesModule === null ? bannerFrom("routes/") : bannerFrom("routes/", LOCALES_MODULE),
 		"",
 		`import type { ParsedParamsMap } from '${GENERATED_FROM}';`,
 		...withRequest ? [`import type { RouteRequest } from '${ROUTE_REQUEST_FROM}';`] : [],
+		...localesModule === null ? [] : [`import type { LocaleOf } from '${I18N}';`],
 		...wantsState ? [`import type {} from '${options.stateModule}';`] : [],
+		...localesModule === null ? [] : [`import type { locales } from '${localesModule}';`],
 		`import type { paramSchemas, routes, searchReaders } from '${options.routesModule}';`,
 		"",
 		`declare module '${GENERATED_FROM}' {`,
@@ -806,6 +815,7 @@ const emitRegisterModule = (options) => {
 		"}"
 	];
 	if (wantsState) lines.push("", `declare module '${options.stateModule}' {`, "  interface Register {", "    routes: typeof routes;", "  }", "}");
+	if (localesModule !== null) lines.push("", `declare module '${I18N}' {`, "  interface Register {", "    locale: LocaleOf<typeof locales>;", "  }", "}");
 	lines.push("");
 	return lines.join("\n");
 };
@@ -855,12 +865,13 @@ const scanRoutes = async (dir) => {
 * person reads the file: `export const paramsSchema`, `export {
 * paramsSchema }`, and a destructured `export const { paramsSchema } =
 * locales` are all an export; the same words inside a string or a comment
-* are not, and `export type paramsSchema` is a type. A file that does not
-* parse exports nothing; the build reports the syntax error itself, where it
-* can name the line.
+* are not, and `export type paramsSchema` is a type. `file` is the module's
+* name, whose extension says whether it is TSX. A file that does not parse
+* exports nothing; the build reports the syntax error itself, where it can
+* name the line.
 */
-const exportsOf = (source) => {
-	const { errors, module } = parseSync("route.tsx", source, { sourceType: "module" });
+const exportsOf = (source, file) => {
+	const { errors, module } = parseSync(file, source, { sourceType: "module" });
 	if (errors.length > 0) return /* @__PURE__ */ new Set();
 	return new Set(module.staticExports.flatMap((statement) => statement.entries.filter((entry) => !entry.isType).map((entry) => entry.exportName.kind === "None" ? "*" : entry.exportName.name ?? "default")));
 };
@@ -876,7 +887,7 @@ const READS_EXPORTS = /* @__PURE__ */ new Set([
 */
 const readExports = async (routesDir, files) => new Map(await Promise.all(files.filter((file) => READS_EXPORTS.has(slotOf(file) ?? "")).map(async (file) => {
 	try {
-		return [file, exportsOf(await readFile(path.join(routesDir, file), "utf8"))];
+		return [file, exportsOf(await readFile(path.join(routesDir, file), "utf8"), file)];
 	} catch {
 		return [file, /* @__PURE__ */ new Set()];
 	}
@@ -900,15 +911,41 @@ const silentRoutes = (exported) => [...exported].filter(([file, names]) => slotO
 	path: file,
 	message: `exports none of ${ROUTE_METHODS.join(", ")} — a route.ts answers the methods it exports`
 }));
-const dependsOnState = async (root) => {
+/** Whether the application's manifest lists `name`. */
+const dependsOn = async (root, name) => {
 	try {
 		const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
-		return "@k8ordo/state" in (manifest.dependencies ?? {}) || "@k8ordo/state" in (manifest.devDependencies ?? {});
+		return name in (manifest.dependencies ?? {}) || name in (manifest.devDependencies ?? {});
 	} catch {
 		return false;
 	}
 };
 /**
+* Where the application declares its locale set: `null` when it does not
+* depend on `@k8ordo/i18n`, the package does not resolve from the root, or
+* there is no {@link LOCALES_MODULE}.
+*/
+const localeSetOf = async (root) => {
+	if (!await dependsOn(root, "@k8ordo/i18n")) return null;
+	const module = path.join(root, LOCALES_MODULE);
+	let source;
+	try {
+		findPackageJSON("@k8ordo/i18n", module);
+		source = await readFile(module, "utf8");
+	} catch {
+		return null;
+	}
+	return {
+		module,
+		exportsLocales: exportsOf(source, module).has("locales")
+	};
+};
+/**
+* Without the generated `Register`, `@k8ordo/i18n` holds a message to no
+* locale set, and nothing else would say so.
+*/
+const LOCALES_UNEXPORTED = `${LOCALES_MODULE} does not export \`locales\` by name (\`export *\` and a type-only export do not count), so @k8ordo/i18n's Register is not generated and a message missing a locale compiles — export the locale set from it as \`locales\``;
+/**
 * Writes what the application would otherwise hand-write: the route table
 * and the type wiring. Nothing here decides anything the grammar has not
 * already decided — problems come back for the caller to report.
@@ -917,7 +954,7 @@ const generate = async (options) => {
 	const files = await scanRoutes(options.routesDir);
 	const parsed = parseRouteTree(files);
 	const exported = await readExports(options.routesDir, files);
-	const withState = await dependsOnState(options.root);
+	const withState = await dependsOn(options.root, "@k8ordo/state");
 	const withSearch = pagesReadingSearch(exported);
 	const problems = [
 		...parsed.problems,
@@ -928,11 +965,13 @@ const generate = async (options) => {
 	const { tree } = parsed;
 	if (problems.length > 0) return {
 		problems,
+		warnings: [],
 		routesModule: path.join(options.outDir, "routes.gen.ts")
 	};
-	const toRoutes = path.relative(options.outDir, options.routesDir).replaceAll(path.sep, "/");
+	const toRoutes = importPath(options.outDir, options.routesDir);
+	const localeSet = await localeSetOf(options.root);
 	const routesSource = emitRoutesModule(tree, {
-		importPrefix: toRoutes.startsWith(".") ? toRoutes : `./${toRoutes}`,
+		importPrefix: toRoutes,
 		mode: options.mode,
 		withParams: new Set([...exported].filter(([, names]) => names.has("paramsSchema")).map(([file]) => file)),
 		withSearch
@@ -940,6 +979,7 @@ const generate = async (options) => {
 	const registerSource = emitRegisterModule({
 		routesModule: "./routes.gen",
 		stateModule: withState ? "@k8ordo/state" : null,
+		localesModule: localeSet?.exportsLocales === true ? importPath(options.outDir, localeSet.module.replace(/\.ts$/u, "")) : null,
 		mode: options.mode
 	});
 	await mkdir(options.outDir, { recursive: true });
@@ -949,9 +989,15 @@ const generate = async (options) => {
 	await writeIfChanged(path.join(options.outDir, ".gitignore"), `# Generated by ${FRAMEWORK}.\n*\n`);
 	return {
 		problems,
+		warnings: localeSet?.exportsLocales === false ? [LOCALES_UNEXPORTED] : [],
 		routesModule
 	};
 };
+/** The relative specifier the generated files import `to` by, from `from`. */
+const importPath = (from, to) => {
+	const relative = path.relative(from, to).replaceAll(path.sep, "/");
+	return relative.startsWith(".") ? relative : `./${relative}`;
+};
 /** Rewriting an unchanged file would restart HMR for no reason. */
 const writeIfChanged = async (file, content) => {
 	try {
@@ -971,7 +1017,7 @@ const SERVER_REFERENCES_ONLY = /dynamically imported by \S*virtual:vite-rsc\/ser
 const OUT_DIR = ".k8ordo";
 const ESM_ENTRY = "[name].js";
 /** Vite's own answer, so nothing downstream can disagree with it. */
-const isProduction = (mode) => (process.env["NODE_ENV"] ?? process.env["VITE_USER_NODE_ENV"] ?? mode) === "production";
+const isProduction = (mode) => (process.env.NODE_ENV ?? process.env.VITE_USER_NODE_ENV ?? mode) === "production";
 /**
 * Client components reach the browser as RSC references, discovered while
 * rendering rather than by crawling the client entry — so React itself is
@@ -1019,6 +1065,7 @@ const FAMILY = /^@k8ordo\//u;
 const engine = (options, host) => {
 	let root = "";
 	let routesDir = "";
+	let localesModule = "";
 	let outDir = "";
 	let logger;
 	let devServer;
@@ -1032,7 +1079,7 @@ const engine = (options, host) => {
 		mode: host.mode
 	});
 	return [
-		react(),
+		react({ compiler: options.reactCompiler === true }),
 		rsc(),
 		{
 			name: "k8ordo:engine",
@@ -1084,6 +1131,7 @@ const engine = (options, host) => {
 				if (!config.base.startsWith("/") || config.base.startsWith("//")) throw new Error(`k8ordo serves its pages under Vite's base, so base has to be a path from the root, like '/docs/' — got '${config.base}'`);
 				({root, logger} = config);
 				routesDir = path.resolve(root, options.routesDir ?? "src/routes");
+				localesModule = path.resolve(root, LOCALES_MODULE);
 				outDir = path.resolve(root, OUT_DIR);
 			},
 			buildApp: {
@@ -1101,7 +1149,8 @@ const engine = (options, host) => {
 				}
 			},
 			async buildStart() {
-				const { problems } = await generate(generateOptions());
+				const { problems, warnings } = await generate(generateOptions());
+				for (const warning of warnings) logger.warnOnce(`k8ordo: ${warning}`);
 				if (problems.length > 0) this.error(`routes/ is not a valid pathname space:\n${problems.map((problem) => `  routes/${problem.path}: ${problem.message}`).join("\n")}`);
 			},
 			configureServer(server) {
@@ -1109,11 +1158,14 @@ const engine = (options, host) => {
 				devServer = server;
 			},
 			async watchChange(file) {
-				if (!path.resolve(file).startsWith(`${routesDir}${path.sep}`)) return;
+				const changed = path.resolve(file);
+				if (!changed.startsWith(`${routesDir}${path.sep}`) && changed !== localesModule) return;
 				const run = generating.then(() => generate(generateOptions()));
 				generating = run.then(() => void 0, () => void 0);
-				const { problems } = await run;
+				const { problems, warnings } = await run;
 				for (const problem of problems) logger.error(`routes/${problem.path}: ${problem.message}`);
+				for (const warning of warnings) logger.warnOnce(`k8ordo: ${warning}`);
+				if (changed === localesModule) return;
 				for (const environment of Object.values(devServer?.environments ?? {})) {
 					const { moduleGraph } = environment;
 					for (const module of moduleGraph.getModulesByFile(routesModule()) ?? []) moduleGraph.invalidateModule(module);
@@ -1267,7 +1319,7 @@ const serverMode = () => ({
 		order: "post",
 		async handler(builder) {
 			const { root, logger } = builder.config;
-			const clientOut = builder.environments["client"]?.config.build.outDir;
+			const clientOut = builder.environments.client?.config.build.outDir;
 			if (clientOut === void 0) throw new Error("server build ran without the client build");
 			const client = path.resolve(root, clientOut);
 			const count = await precompress(client);
@@ -1299,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) => {
@@ -1322,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`);
@@ -1928,7 +1983,7 @@ const staticMode = (options) => {
 		},
 		async configurePreviewServer(server) {
 			const { config } = server;
-			const client = path.resolve(config.root, config.environments["client"]?.build.outDir ?? "dist/client");
+			const client = path.resolve(config.root, config.environments.client?.build.outDir ?? "dist/client");
 			const rules = await readRules(client);
 			const answeredHere = async (request, response) => {
 				const url = new URL(`${ORIGIN}${request.url ?? "/"}`);
@@ -1990,7 +2045,7 @@ const staticMode = (options) => {
 				const file = path.relative(routesDir, module).split(path.sep).join("/");
 				const slot = file.startsWith("..") ? null : slotOf(file);
 				if (slot === "guard") throw new Error(guardRefusal([path.relative(root, module)]));
-				const names = READ_BY_NAME.has(slot ?? "") ? exportsOf(await readFile(module, "utf8")) : /* @__PURE__ */ new Set();
+				const names = READ_BY_NAME.has(slot ?? "") ? exportsOf(await readFile(module, "utf8"), file) : /* @__PURE__ */ new Set();
 				if (names.has("*")) throw new Error(reexportRefusal([path.relative(root, module)]));
 				const methods = slot === "route" ? unwritable(names) : [];
 				if (methods.length > 0) throw new Error(routeRefusal([[path.relative(root, module), methods]]));
@@ -2012,8 +2067,8 @@ const staticMode = (options) => {
 				const importers = [...serverImporters].toSorted();
 				const unanswerable = [...actions.length > 0 ? [actionRefusal(actions)] : [], ...importers.length > 0 ? [serverImportRefusal(importers)] : []];
 				if (unanswerable.length > 0) throw new Error(unanswerable.join("\n\n"));
-				const rscOut = builder.environments["rsc"]?.config.build.outDir;
-				const client = builder.environments["client"]?.config;
+				const rscOut = builder.environments.rsc?.config.build.outDir;
+				const client = builder.environments.client?.config;
 				if (rscOut === void 0 || client === void 0) throw new Error("static build ran without the rsc/client builds");
 				const clientDir = path.resolve(root, client.build.outDir);
 				const origin = options.site === void 0 ? ORIGIN : new URL(options.site).origin;
@@ -2033,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 () => {
@@ -2101,9 +2159,10 @@ 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");
+				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(", ")})`;
 				builder.config.logger.info(`k8ordo: wrote ${String(plan.paths.length)} routes${shells}${unmatched === null ? "" : " and 404.html"}${options.site === void 0 ? "" : " and sitemap.xml"}${plan.shells.length === 0 ? "" : " and _redirects"}`);
 			}
@@ -2157,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

@@ -133,10 +133,13 @@ export default defineConfig({ plugins: [framework({ mode: 'static' })] });
 // or framework({ mode: 'server' })
 ```
 
-The framework writes the route table and its types into `.k8ordo/`. Add it
-to `include` in `tsconfig.json` as a glob, `.k8ordo/**/*.ts` (an entry
-naming only the dot-directory leaves its files out), and `href()`'s paths
-and a page's `params` are typed. The generated files import without file
+The framework writes the route table and its types into `.k8ordo/`,
+including the `Register` augmentations an application would otherwise write
+by hand — the table's, and `@k8ordo/i18n`'s when `src/i18n.ts` exports the
+locale set by the name `locales`. Add it to `include` in `tsconfig.json` as
+a glob, `.k8ordo/**/*.ts` (an entry naming only the dot-directory leaves its
+files out), and `href()`'s paths and a page's `params` are typed, and with
+that export every message's locales. The generated files import without file
 extensions, so they resolve under `moduleResolution: "bundler"`, as Vite
 does. A fresh clone has no `.k8ordo/` until `vite build` or `vite dev`
 writes it, so CI runs the build before `tsc`
@@ -231,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.
 
@@ -242,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,14 +52,18 @@ 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
 
 - [Routing](references/routing.md): the `routes/` grammar and every refusal
   the build names, where a `fallback.tsx` may sit, how a page is sent in
   each mode, `loading.tsx`, `route.ts` (methods and `405` under server
-  mode, a file under static mode), the generated `.k8ordo/` files, titles,
+  mode, a file under static mode), the generated `.k8ordo/` files (the
+  route table, and the `Register`s: the table's, and `@k8ordo/i18n`'s when
+  `src/i18n.ts` exports `locales` by name), titles,
   and fetching the next page ahead (`data-k8ordo-prefetch`).
 - [Parameters](references/params.md): `paramsSchema` — a refused value is a
   pathname the pattern does not answer — and, under static mode, the `paths`
@@ -101,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
@@ -128,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
@@ -177,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