@k8ordo/framework 0.1.0 → 1.0.0

package/README.md

@@ -154,7 +154,10 @@ error.tsx, loading.tsx, fallback.tsx, redirect.ts, guard.ts and route.ts;
 components go in `src/components/` and every other module (Server Actions,
 schemas, state definitions, data, helpers) in `src/lib/`, since a
 `_`-prefixed directory there is a URL segment, not a private one. Never
-edit `.k8ordo/` — it is generated. Import from `@k8ordo/framework` (never
+edit `.k8ordo/` — it is generated, with the `Register` augmentations: the
+route table's, and `@k8ordo/i18n`'s when `src/i18n.ts` exports the locale
+set by the name `locales` (write that one by hand only when the set lives
+elsewhere). Import from `@k8ordo/framework` (never
 `@k8ordo/router`), and the request API from `@k8ordo/framework/server`,
 which `mode: 'static'` refuses. Build links with `href()`; search params
 are `@k8ordo/state`'s.

package/dist/runtime/app-router.d.mts

@@ -1,6 +1,10 @@
+import { Payload } from "./payload.mjs";
 import { ReactNode } from "react";
 //#region src/runtime/app-router.d.ts
 export declare const setDocumentClient: (client: string) => void;
+/** What a Server Action's answer does to the document, once it is read. */
+export declare const answerAction: (payload: Payload) => Promise<unknown>;
+export declare const setPayloadReader: (read: (stream: ReadableStream<Uint8Array>) => Promise<Payload>) => void;
 /**
  * The client half under the framework: the tree comes from the server, so
  * there is no route table in the browser at all — only navigation. The

package/dist/runtime/app-router.mjs

@@ -1,21 +1,19 @@
 "use client";
-import { ACTION_ID_HEADER } from "./payload.mjs";
 import { payloadPathFor } from "./payload-path.mjs";
 import { ShowNotFound } from "./fallback-boundary.mjs";
 import { isPayload } from "./is-payload.mjs";
 import { createPrefetchCache, prefetchTargetOf } from "./prefetch.mjs";
 import { Recover, markNavigated, reloadInstead } from "./recover.mjs";
 import { NavigationGeneration, PathnameProvider, useInterceptedNavigation, withoutBase } from "@k8ordo/router";
-import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback } from "@vitejs/plugin-rsc/browser";
 import { startTransition, useDeferredValue, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/runtime/app-router.tsx
 /**
 * Where a Server Action's answer lands. The callback has to be registered
 * before any client component can call one, which is earlier than a component
-* can offer its own setter — so the wiring is here and the mounted router
-* lends it a way to apply what comes back, and to drop the pages it fetched
-* ahead, which the action may have changed.
+* can offer its own setter — so `answerAction` is module-level and the
+* mounted router lends it a way to apply what comes back, and to drop the
+* pages it fetched ahead, which the action may have changed.
 */
 let mounted = null;
 /**
@@ -36,13 +34,8 @@ const setDocumentClient = (client) => {
 * document load brings the script that can.
 */
 const canRender = (payload) => payload.client === documentClient;
-setServerCallback(async (id, args) => {
-	const temporaryReferences = createTemporaryReferenceSet();
-	const payload = await createFromFetch(fetch(location.href, {
-		method: "POST",
-		headers: { [ACTION_ID_HEADER]: id },
-		body: await encodeReply(args, { temporaryReferences })
-	}), { temporaryReferences });
+/** What a Server Action's answer does to the document, once it is read. */
+const answerAction = async (payload) => {
 	mounted?.forgetPrefetched();
 	if (payload.redirect !== void 0) {
 		await navigation.navigate(payload.redirect).finished;
@@ -51,7 +44,11 @@ setServerCallback(async (id, args) => {
 	if (!canRender(payload)) return reloadInstead();
 	mounted?.apply(payload);
 	return payload.returnValue;
-});
+};
+let readPayload = () => Promise.reject(/* @__PURE__ */ new Error("k8ordo: payloads are read in the browser only"));
+const setPayloadReader = (read) => {
+	readPayload = read;
+};
 /**
 * The request each fetched payload is still streaming in on. A payload
 * resolves once its top arrives, and a page that awaits its data arrives
@@ -77,7 +74,7 @@ const fetchPage = async (payloadPath, signal) => {
 	signal.addEventListener("abort", cancel, { once: true });
 	const response = await fetch(payloadPath, { signal: request.signal });
 	if (!isPayload(response)) return null;
-	const payload = await createFromReadableStream(response.body);
+	const payload = await readPayload(response.body);
 	streams.set(payload, {
 		cancel: () => {
 			request.abort();
@@ -272,4 +269,4 @@ function AppRouter({ pathname, search, tree, notFound }) {
 	});
 }
 //#endregion
-export { AppRouter, setDocumentClient };
+export { AppRouter, answerAction, setDocumentClient, setPayloadReader };

package/dist/runtime/browser-payloads.d.mts

@@ -0,0 +1,8 @@
+//#region src/runtime/browser-payloads.d.ts
+/**
+ * Hands app-router the browser's Flight client: how a fetched payload is
+ * read, and where a Server Action is sent. Called by the browser entry
+ * before anything renders.
+ */
+export declare const connectAppRouter: () => void;
+//#endregion

package/dist/runtime/browser-payloads.mjs

@@ -0,0 +1,23 @@
+import { ACTION_ID_HEADER } from "./payload.mjs";
+import { answerAction, setPayloadReader } from "./app-router.mjs";
+import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback } from "@vitejs/plugin-rsc/browser";
+//#region src/runtime/browser-payloads.ts
+/**
+* Hands app-router the browser's Flight client: how a fetched payload is
+* read, and where a Server Action is sent. Called by the browser entry
+* before anything renders.
+*/
+const connectAppRouter = () => {
+	setPayloadReader((stream) => createFromReadableStream(stream));
+	setServerCallback(async (id, args) => {
+		const temporaryReferences = createTemporaryReferenceSet();
+		const payload = await createFromFetch(fetch(location.href, {
+			method: "POST",
+			headers: { [ACTION_ID_HEADER]: id },
+			body: await encodeReply(args, { temporaryReferences })
+		}), { temporaryReferences });
+		return answerAction(payload);
+	});
+};
+//#endregion
+export { connectAppRouter };

package/dist/runtime/entry.browser.mjs

@@ -1,11 +1,13 @@
 import { AppRouter, setDocumentClient } from "./app-router.mjs";
+import { connectAppRouter } from "./browser-payloads.mjs";
 import { mount } from "./mount.mjs";
 import { reportCaught } from "./page-boundary.mjs";
 import { whenRevealed } from "./revealed.mjs";
-import { createFromReadableStream } from "@vitejs/plugin-rsc/browser";
 import { jsx } from "react/jsx-runtime";
+import { createFromReadableStream } from "@vitejs/plugin-rsc/browser";
 import { rscStream } from "rsc-html-stream/client";
 //#region src/runtime/entry.browser.tsx
+connectAppRouter();
 const payload = await createFromReadableStream(rscStream);
 setDocumentClient(payload.client);
 await whenRevealed();

package/dist/serve.mjs

@@ -120,7 +120,7 @@ const sendAnswer = async (incoming, response, result) => {
 	const encoding = compressible ? negotiateEncoding(incoming.headers["accept-encoding"], ENCODINGS) : null;
 	if (compressible) {
 		const vary = result.headers.get("vary");
-		headers["vary"] = vary === null ? "Accept-Encoding" : `${vary}, Accept-Encoding`;
+		headers.vary = vary === null ? "Accept-Encoding" : `${vary}, Accept-Encoding`;
 	}
 	if (encoding !== null) {
 		headers["content-encoding"] = encoding;

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;
@@ -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);
@@ -1928,7 +1980,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 +2042,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 +2064,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;
@@ -2103,7 +2155,7 @@ const staticMode = (options) => {
 					rewrites,
 					notFound: unmatched !== null
 				});
-				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"}`);
 			}

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`

package/docs/llms.txt

@@ -59,7 +59,9 @@ Start with GUIDE.md, then follow the reference most relevant to the task.
 - [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`

package/docs/references/deploy.md

@@ -465,8 +465,8 @@ on evil.test would pass the check.
 
 ```ts
 // vite.config.ts
-import { framework } from '@k8ordo/framework/vite';
 import { vercel } from '@k8ordo/framework/vercel';
+import { framework } from '@k8ordo/framework/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({

package/docs/references/routing.md

@@ -311,10 +311,10 @@ import { defineRoutes } from '@k8ordo/framework/generated';
 import type { ParamsOf, ParsedParams } from '@k8ordo/framework/generated';
 import type { ComponentType, ReactNode } from 'react';
 
+import layout from '../src/routes/layout';
 import page from '../src/routes/page';
-import products_page from '../src/routes/products/page';
 import products_id_page from '../src/routes/products/[id]/page';
-import layout from '../src/routes/layout';
+import products_page from '../src/routes/products/page';
 
 type Page<P extends string, S extends readonly unknown[] = []> = ComponentType<{
   params: ParsedParams<P, S>;
@@ -384,6 +384,35 @@ import { href } from '@k8ordo/framework';
 <a href={href('/products/:id', { id })}>…</a>; // checked against routes/
 ```
 
+It registers the locale set with `@k8ordo/i18n` too, when the application
+has one: its `package.json` lists `@k8ordo/i18n` (in `dependencies` or
+`devDependencies`), and `src/i18n.ts` exports the set as `locales`. That is
+the `Register` an application outside the framework writes by hand, so here
+it writes none, and a message missing a locale does not compile:
+
+```ts
+// .k8ordo/register.gen.ts (the part for @k8ordo/i18n)
+import type { LocaleOf } from '@k8ordo/i18n';
+
+import type { locales } from '../src/i18n';
+
+declare module '@k8ordo/i18n' {
+  interface Register {
+    locale: LocaleOf<typeof locales>;
+  }
+}
+```
+
+The export is read from the file's syntax, as a route file's are, and never
+by running it: `export const locales = defineLocales(…)` and
+`export { locales } from './locales'` count, a type-only export and
+`export *` do not. A `src/i18n.ts` without the export gets nothing
+generated and a warning naming it, since every message would compile
+unchecked; an application that keeps its set elsewhere writes the
+`Register` by hand. `vite dev` writes the file again as `src/i18n.ts` comes,
+goes, or gains or loses the export. A hand-written augmentation left in the
+application still compiles beside it, since both declare the same type.
+
 Neither file names `@k8ordo/router`: they import from
 `@k8ordo/framework/generated`, so the application's code, generated or not,
 reads only the framework.
@@ -397,7 +426,8 @@ vite build && tsc --noEmit
 ```
 
 Without the files, `tsc` checks against no table: `href` takes any string,
-params typed by a `paramsSchema` are strings, and under `mode: 'server'` the
+params typed by a `paramsSchema` are strings, a message missing a locale
+compiles, and under `mode: 'server'` the
 `request` and `search` props are not in `PageProps` or `LayoutProps`, so a
 page that reads them fails with `Property 'request' does not exist`. That is
 the error static mode gives on purpose, but here the mode is not the cause.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/framework",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "The k8ordo framework: routes/ compiled into React Server Components, run with or without a server.",
   "keywords": [
     "k8ordo",
@@ -61,8 +61,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@vitejs/plugin-react": "6.1.1",
-    "@vitejs/plugin-rsc": "0.5.35",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitejs/plugin-rsc": "0.5.36",
     "compressible": "2.0.18",
     "fresh": "2.0.0",
     "mime-types": "3.0.2",
@@ -79,13 +79,13 @@
     "@types/mime-types": "3.0.1",
     "@types/range-parser": "1.2.7",
     "@types/react": "19.3.0",
-    "publint": "0.3.24",
+    "publint": "0.3.25",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
-    "vite-plus": "0.3.2",
-    "vitest": "5.0.2"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
     "@k8ordo/router": "^1.0.0",