@moku-labs/web 1.5.2 → 1.6.0

package/dist/browser.d.mts

@@ -1550,15 +1550,24 @@ declare function defineRoutes<T extends RouteMap>(routes: T): T;
  * directly: no `app.router` reference, no manual "bind", no module global, no
  * "not bound" guard, and no createApp ↔ routes cycle.
  *
+ * Pass `defaultLocale` so the builder serves that locale at BARE paths, matching the
+ * runtime `router.toUrl` (which reads the default locale from the i18n plugin):
+ * `toUrl("home", { lang: defaultLocale })` then resolves to `/` instead of
+ * `/{defaultLocale}/`. It is app-free, so the default locale cannot be inferred — the
+ * consumer supplies it (e.g. `createUrls(routes, "en")`). Omit it to keep every locale
+ * prefixed.
+ *
  * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+ * @param defaultLocale - The locale to serve bare (its `{lang:?}` prefix is omitted).
  * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
  * @example
  * ```ts
- * const url = createUrls(routes);
- * url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+ * const url = createUrls(routes, "en");
+ * url.toUrl("article", { lang: "en", slug: "hello" }); // "/hello/"
+ * url.toUrl("article", { lang: "ru", slug: "hello" }); // "/ru/hello/"
  * ```
  */
-declare function createUrls<T extends RouteMap>(routes: T): Urls<T>;
+declare function createUrls<T extends RouteMap>(routes: T, defaultLocale?: string): Urls<T>;
 //#endregion
 //#region src/plugins/router/index.d.ts
 /**

package/dist/browser.mjs

@@ -1587,15 +1587,22 @@ function patternToUrlPattern(pattern, variant, langRegex) {
 * param is absent has its segment skipped entirely (no empty segment), so a missing
 * `{lang:?}` collapses cleanly instead of leaving a double slash.
 *
+* The default locale is served at BARE paths: when `defaultLocale` is given, the
+* optional `{lang:?}` segment is also skipped for it (so `{ lang: defaultLocale }`
+* resolves to `/…` while every other locale keeps its `/{locale}/…` prefix).
+*
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
+* @param defaultLocale - The locale served bare (its `{lang:?}` segment is omitted).
 * @returns The resolved relative URL string.
 * @example
 * ```ts
 * buildUrl("/{slug}/", { slug: "hello" }); // "/hello/"
+* buildUrl("/{lang:?}/", { lang: "en" }, "en"); // "/"
+* buildUrl("/{lang:?}/", { lang: "ru" }, "en"); // "/ru/"
 * ```
 */
-function buildUrl(pattern, params) {
+function buildUrl(pattern, params, defaultLocale) {
 	const out = [];
 	for (const segment of pattern.split("/")) {
 		const placeholder = parsePlaceholder(segment);
@@ -1605,6 +1612,7 @@ function buildUrl(pattern, params) {
 		}
 		const value = params[placeholder.name] ?? "";
 		if (placeholder.optional && value === "") continue;
+		if (placeholder.name === "lang" && placeholder.optional && value === defaultLocale) continue;
 		out.push(value);
 	}
 	return out.join("/");
@@ -1614,14 +1622,15 @@ function buildUrl(pattern, params) {
 *
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
+* @param defaultLocale - The locale served bare (forwarded to {@link buildUrl}).
 * @returns The output file path, e.g. `hello/index.html`.
 * @example
 * ```ts
 * buildFilePath("/{slug}/", { slug: "hello" });
 * ```
 */
-function buildFilePath(pattern, params) {
-	const cleanPath = buildUrl(pattern, params).replace(/^\//, "").replace(/\/$/, "");
+function buildFilePath(pattern, params, defaultLocale) {
+	const cleanPath = buildUrl(pattern, params, defaultLocale).replace(/^\//, "").replace(/\/$/, "");
 	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
 }
 /**
@@ -1650,15 +1659,16 @@ function buildMatchers(pattern, locales) {
 * pattern.
 *
 * @param pattern - The route pattern bound into the closure.
+* @param defaultLocale - The locale served bare (bound into the closure).
 * @returns A function mapping params to the resolved relative URL.
 * @example
 * ```ts
-* const toUrl = createToUrlFn("/{slug}/");
+* const toUrl = createToUrlFn("/{slug}/", "en");
 * toUrl({ slug: "x" }); // "/x/"
 * ```
 */
-function createToUrlFunction(pattern) {
-	return (params) => buildUrl(pattern, params);
+function createToUrlFunction(pattern, defaultLocale) {
+	return (params) => buildUrl(pattern, params, defaultLocale);
 }
 /**
 * Build the `toFile` closure for a route — resolves the output file path from
@@ -1667,15 +1677,16 @@ function createToUrlFunction(pattern) {
 *
 * @param pattern - The route pattern bound into the closure.
 * @param definition - The route definition carrying any `toFile` override.
+* @param defaultLocale - The locale served bare (bound into the closure).
 * @returns A function mapping params to the output file path.
 * @example
 * ```ts
-* const toFile = createToFileFn("/{slug}/", definition);
+* const toFile = createToFileFn("/{slug}/", definition, "en");
 * toFile({ slug: "x" }); // "x/index.html"
 * ```
 */
-function createToFileFunction(pattern, definition) {
-	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params);
+function createToFileFunction(pattern, definition, defaultLocale) {
+	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params, defaultLocale);
 }
 /**
 * Compile a single route definition into its `CompiledRoute` entry.
@@ -1692,8 +1703,8 @@ function createToFileFunction(pattern, definition) {
 function compileRoute(name, definition, input) {
 	const { pattern } = definition;
 	const matchers = buildMatchers(pattern, input.locales);
-	const toUrl = createToUrlFunction(pattern);
-	const toFile = createToFileFunction(pattern, definition);
+	const toUrl = createToUrlFunction(pattern, input.defaultLocale);
+	const toFile = createToFileFunction(pattern, definition, input.defaultLocale);
 	return {
 		name,
 		pattern,
@@ -2124,15 +2135,24 @@ function defineRoutes(routes) {
 * directly: no `app.router` reference, no manual "bind", no module global, no
 * "not bound" guard, and no createApp ↔ routes cycle.
 *
+* Pass `defaultLocale` so the builder serves that locale at BARE paths, matching the
+* runtime `router.toUrl` (which reads the default locale from the i18n plugin):
+* `toUrl("home", { lang: defaultLocale })` then resolves to `/` instead of
+* `/{defaultLocale}/`. It is app-free, so the default locale cannot be inferred — the
+* consumer supplies it (e.g. `createUrls(routes, "en")`). Omit it to keep every locale
+* prefixed.
+*
 * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+* @param defaultLocale - The locale to serve bare (its `{lang:?}` prefix is omitted).
 * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
 * @example
 * ```ts
-* const url = createUrls(routes);
-* url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+* const url = createUrls(routes, "en");
+* url.toUrl("article", { lang: "en", slug: "hello" }); // "/hello/"
+* url.toUrl("article", { lang: "ru", slug: "hello" }); // "/ru/hello/"
 * ```
 */
-function createUrls(routes) {
+function createUrls(routes, defaultLocale) {
 	return { 
 	/**
 	* Build a route's URL path from its name and params.
@@ -2143,13 +2163,13 @@ function createUrls(routes) {
 	* @throws {Error} If `name` is not present in the route map.
 	* @example
 	* ```ts
-	* url.toUrl("home", { lang: "en" }); // "/en/"
+	* url.toUrl("home", { lang: "ru" }); // "/ru/"
 	* ```
 	*/
 toUrl(name, params = {}) {
 		const definition = routes[name];
 		if (!definition) throw new Error(`[web] router: unknown route name "${String(name)}".\n  Check the name matches a key in the route map passed to createUrls.`);
-		return buildUrl(definition.pattern, params);
+		return buildUrl(definition.pattern, params, defaultLocale);
 	} };
 }
 //#endregion
@@ -4424,10 +4444,31 @@ function contentApi(ctx) {
 */
 async function resolveArticle(ctx, slug, locale) {
 	const native = await ctx.provider.readArticle(slug, locale, locale, false);
-	if (native !== null) return native;
+	if (native !== null) return bareDefaultLocaleUrl(ctx, native);
 	const fallbackLocale = ctx.defaultLocale();
 	if (fallbackLocale === locale) return null;
-	return ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+	const fallback = await ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+	return fallback === null ? fallback : bareDefaultLocaleUrl(ctx, fallback);
+}
+/**
+* The default locale is served at BARE paths, so strip the leading `/{defaultLocale}`
+* from a default-locale article's `url` (`/en/hello/` → `/hello/`). Providers build
+* always-prefixed URLs (they have no i18n access); this is the single place the bare
+* default is applied, so article canonicals + feed GUIDs match the served URL.
+* Idempotent (a bare URL has no prefix to strip) and a no-op for non-default locales.
+*
+* @param ctx - Kernel-free domain context (i18n helpers).
+* @param article - The resolved article (mutated in place).
+* @returns The same article, with a bare `url` when it is the default locale.
+* @example
+* ```ts
+* bareDefaultLocaleUrl(ctx, { ...article, locale: "en", url: "/en/hello/" }).url; // "/hello/"
+* ```
+*/
+function bareDefaultLocaleUrl(ctx, article) {
+	const prefix = `/${ctx.defaultLocale()}`;
+	if (article.locale === ctx.defaultLocale() && article.url.startsWith(`${prefix}/`)) article.url = article.url.slice(prefix.length);
+	return article;
 }
 /**
 * Comparator sorting articles by frontmatter date descending (newest first),

package/dist/index.cjs

@@ -1232,10 +1232,31 @@ function contentApi(ctx) {
 */
 async function resolveArticle(ctx, slug, locale) {
 	const native = await ctx.provider.readArticle(slug, locale, locale, false);
-	if (native !== null) return native;
+	if (native !== null) return bareDefaultLocaleUrl(ctx, native);
 	const fallbackLocale = ctx.defaultLocale();
 	if (fallbackLocale === locale) return null;
-	return ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+	const fallback = await ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+	return fallback === null ? fallback : bareDefaultLocaleUrl(ctx, fallback);
+}
+/**
+* The default locale is served at BARE paths, so strip the leading `/{defaultLocale}`
+* from a default-locale article's `url` (`/en/hello/` → `/hello/`). Providers build
+* always-prefixed URLs (they have no i18n access); this is the single place the bare
+* default is applied, so article canonicals + feed GUIDs match the served URL.
+* Idempotent (a bare URL has no prefix to strip) and a no-op for non-default locales.
+*
+* @param ctx - Kernel-free domain context (i18n helpers).
+* @param article - The resolved article (mutated in place).
+* @returns The same article, with a bare `url` when it is the default locale.
+* @example
+* ```ts
+* bareDefaultLocaleUrl(ctx, { ...article, locale: "en", url: "/en/hello/" }).url; // "/hello/"
+* ```
+*/
+function bareDefaultLocaleUrl(ctx, article) {
+	const prefix = `/${ctx.defaultLocale()}`;
+	if (article.locale === ctx.defaultLocale() && article.url.startsWith(`${prefix}/`)) article.url = article.url.slice(prefix.length);
+	return article;
 }
 /**
 * Comparator sorting articles by frontmatter date descending (newest first),
@@ -2145,15 +2166,22 @@ function patternToUrlPattern(pattern, variant, langRegex) {
 * param is absent has its segment skipped entirely (no empty segment), so a missing
 * `{lang:?}` collapses cleanly instead of leaving a double slash.
 *
+* The default locale is served at BARE paths: when `defaultLocale` is given, the
+* optional `{lang:?}` segment is also skipped for it (so `{ lang: defaultLocale }`
+* resolves to `/…` while every other locale keeps its `/{locale}/…` prefix).
+*
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
+* @param defaultLocale - The locale served bare (its `{lang:?}` segment is omitted).
 * @returns The resolved relative URL string.
 * @example
 * ```ts
 * buildUrl("/{slug}/", { slug: "hello" }); // "/hello/"
+* buildUrl("/{lang:?}/", { lang: "en" }, "en"); // "/"
+* buildUrl("/{lang:?}/", { lang: "ru" }, "en"); // "/ru/"
 * ```
 */
-function buildUrl(pattern, params) {
+function buildUrl(pattern, params, defaultLocale) {
 	const out = [];
 	for (const segment of pattern.split("/")) {
 		const placeholder = parsePlaceholder(segment);
@@ -2163,6 +2191,7 @@ function buildUrl(pattern, params) {
 		}
 		const value = params[placeholder.name] ?? "";
 		if (placeholder.optional && value === "") continue;
+		if (placeholder.name === "lang" && placeholder.optional && value === defaultLocale) continue;
 		out.push(value);
 	}
 	return out.join("/");
@@ -2172,14 +2201,15 @@ function buildUrl(pattern, params) {
 *
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
+* @param defaultLocale - The locale served bare (forwarded to {@link buildUrl}).
 * @returns The output file path, e.g. `hello/index.html`.
 * @example
 * ```ts
 * buildFilePath("/{slug}/", { slug: "hello" });
 * ```
 */
-function buildFilePath(pattern, params) {
-	const cleanPath = buildUrl(pattern, params).replace(/^\//, "").replace(/\/$/, "");
+function buildFilePath(pattern, params, defaultLocale) {
+	const cleanPath = buildUrl(pattern, params, defaultLocale).replace(/^\//, "").replace(/\/$/, "");
 	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
 }
 /**
@@ -2208,15 +2238,16 @@ function buildMatchers(pattern, locales) {
 * pattern.
 *
 * @param pattern - The route pattern bound into the closure.
+* @param defaultLocale - The locale served bare (bound into the closure).
 * @returns A function mapping params to the resolved relative URL.
 * @example
 * ```ts
-* const toUrl = createToUrlFn("/{slug}/");
+* const toUrl = createToUrlFn("/{slug}/", "en");
 * toUrl({ slug: "x" }); // "/x/"
 * ```
 */
-function createToUrlFunction(pattern) {
-	return (params) => buildUrl(pattern, params);
+function createToUrlFunction(pattern, defaultLocale) {
+	return (params) => buildUrl(pattern, params, defaultLocale);
 }
 /**
 * Build the `toFile` closure for a route — resolves the output file path from
@@ -2225,15 +2256,16 @@ function createToUrlFunction(pattern) {
 *
 * @param pattern - The route pattern bound into the closure.
 * @param definition - The route definition carrying any `toFile` override.
+* @param defaultLocale - The locale served bare (bound into the closure).
 * @returns A function mapping params to the output file path.
 * @example
 * ```ts
-* const toFile = createToFileFn("/{slug}/", definition);
+* const toFile = createToFileFn("/{slug}/", definition, "en");
 * toFile({ slug: "x" }); // "x/index.html"
 * ```
 */
-function createToFileFunction(pattern, definition) {
-	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params);
+function createToFileFunction(pattern, definition, defaultLocale) {
+	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params, defaultLocale);
 }
 /**
 * Compile a single route definition into its `CompiledRoute` entry.
@@ -2250,8 +2282,8 @@ function createToFileFunction(pattern, definition) {
 function compileRoute(name, definition, input) {
 	const { pattern } = definition;
 	const matchers = buildMatchers(pattern, input.locales);
-	const toUrl = createToUrlFunction(pattern);
-	const toFile = createToFileFunction(pattern, definition);
+	const toUrl = createToUrlFunction(pattern, input.defaultLocale);
+	const toFile = createToFileFunction(pattern, definition, input.defaultLocale);
 	return {
 		name,
 		pattern,
@@ -2682,15 +2714,24 @@ function defineRoutes(routes) {
 * directly: no `app.router` reference, no manual "bind", no module global, no
 * "not bound" guard, and no createApp ↔ routes cycle.
 *
+* Pass `defaultLocale` so the builder serves that locale at BARE paths, matching the
+* runtime `router.toUrl` (which reads the default locale from the i18n plugin):
+* `toUrl("home", { lang: defaultLocale })` then resolves to `/` instead of
+* `/{defaultLocale}/`. It is app-free, so the default locale cannot be inferred — the
+* consumer supplies it (e.g. `createUrls(routes, "en")`). Omit it to keep every locale
+* prefixed.
+*
 * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+* @param defaultLocale - The locale to serve bare (its `{lang:?}` prefix is omitted).
 * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
 * @example
 * ```ts
-* const url = createUrls(routes);
-* url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+* const url = createUrls(routes, "en");
+* url.toUrl("article", { lang: "en", slug: "hello" }); // "/hello/"
+* url.toUrl("article", { lang: "ru", slug: "hello" }); // "/ru/hello/"
 * ```
 */
-function createUrls(routes) {
+function createUrls(routes, defaultLocale) {
 	return { 
 	/**
 	* Build a route's URL path from its name and params.
@@ -2701,13 +2742,13 @@ function createUrls(routes) {
 	* @throws {Error} If `name` is not present in the route map.
 	* @example
 	* ```ts
-	* url.toUrl("home", { lang: "en" }); // "/en/"
+	* url.toUrl("home", { lang: "ru" }); // "/ru/"
 	* ```
 	*/
 toUrl(name, params = {}) {
 		const definition = routes[name];
 		if (!definition) throw new Error(`[web] router: unknown route name "${String(name)}".\n  Check the name matches a key in the route map passed to createUrls.`);
-		return buildUrl(definition.pattern, params);
+		return buildUrl(definition.pattern, params, defaultLocale);
 	} };
 }
 //#endregion
@@ -3992,10 +4033,31 @@ function wrap(body) {
 	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>404 — Not Found</title></head><body>${body}</body></html>`;
 }
 /**
+* Resolve the 404 page HTML from `config.notFound`. Precedence: `path` (a
+* complete page file, read verbatim) > `body` (a fragment, wrapped in the
+* minimal shell) > the built-in default.
+*
+* @param notFound - The `config.notFound` value (already known to be truthy).
+* @returns The complete HTML document to write.
+* @example
+* ```ts
+* const html = await resolveHtml({ path: "src/404.html" });
+* ```
+*/
+async function resolveHtml(notFound) {
+	if (typeof notFound === "object" && notFound.path) try {
+		return await (0, node_fs_promises.readFile)(notFound.path, "utf8");
+	} catch (error) {
+		throw new Error(`build:not-found — could not read notFound.path "${notFound.path}"`, { cause: error });
+	}
+	return wrap(typeof notFound === "object" && notFound.body ? notFound.body : DEFAULT_BODY);
+}
+/**
 * Emits `outDir/404.html`. When `config.notFound` is `true`, writes the built-in
-* default page; when it is `{ body }`, writes the supplied HTML body content
-* verbatim inside the document shell. No-op (returns `null`) when `notFound` is
-* false/unset.
+* default page; `{ body }` writes the supplied HTML body content inside the
+* minimal document shell; `{ path }` writes the referenced HTML page file
+* verbatim (the app owns the whole document). No-op (returns `null`) when
+* `notFound` is false/unset.
 *
 * @param ctx - Plugin context (provides `config`, `log`).
 * @returns The written file path, or `null` when disabled.
@@ -4010,10 +4072,10 @@ async function generateNotFound(ctx) {
 		ctx.log.debug("build:not-found", { skipped: true });
 		return null;
 	}
-	const body = typeof notFound === "object" && notFound.body ? notFound.body : DEFAULT_BODY;
+	const html = await resolveHtml(notFound);
 	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
 	const file = node_path$1.default.join(outDir, "404.html");
-	await (0, node_fs_promises.writeFile)(file, wrap(body), "utf8");
+	await (0, node_fs_promises.writeFile)(file, html, "utf8");
 	ctx.log.debug("build:not-found", { path: file });
 	return { path: file };
 }
@@ -5096,7 +5158,24 @@ function renderBodyCached(ctx, instance, routeContext, data, reuse) {
 * ```
 */
 async function writeDocument(outDir, entry, params, html) {
-	const filePath = node_path.default.join(outDir, entry.toFile(params));
+	await writeDocumentAt(outDir, entry.toFile(params), html);
+}
+/**
+* Write an HTML document to an explicit relative path under `outDir`, creating parent
+* directories first. Backs both the canonical page path ({@link writeDocument}) and the
+* default-locale `/{defaultLocale}/…` alias copy ({@link renderInstance}).
+*
+* @param outDir - The build output directory.
+* @param relativeFile - The output file path relative to `outDir` (e.g. `en/index.html`).
+* @param html - The complete HTML document to write.
+* @returns A promise resolved once the file is written.
+* @example
+* ```ts
+* await writeDocumentAt("dist", "en/about/index.html", "<!DOCTYPE html>…");
+* ```
+*/
+async function writeDocumentAt(outDir, relativeFile, html) {
+	const filePath = node_path.default.join(outDir, relativeFile);
 	await (0, node_fs_promises.mkdir)(node_path.default.dirname(filePath), { recursive: true });
 	await (0, node_fs_promises.writeFile)(filePath, html, "utf8");
 }
@@ -5106,14 +5185,19 @@ async function writeDocument(outDir, entry, params, html) {
 * `<head>`/body → assemble the document (template fill or in-code shell) → write.
 * Uses the configured shell `template` when supplied, otherwise the in-code shell.
 *
+* The default locale is served at BARE paths, so each default-locale page on a
+* `{lang:?}` route is ALSO written to `/{defaultLocale}/…` — the SAME rendered HTML (its
+* canonical already points at the bare URL) — so an explicit `/{defaultLocale}/…` link
+* serves the page directly with no redirect. Both pages are returned so each gets a sidecar.
+*
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `has`).
 * @param instance - The concrete page instance to render.
-* @param shell - Per-build wiring shared across instances (asset tags + template).
+* @param shell - Per-build wiring shared across instances (asset tags + template + default locale).
 * @param reuse - Whether this run may reuse a cached body (incremental, no code change).
-* @returns The instance's URL, rendered HTML, loaded data, and client-nav flag.
+* @returns The rendered page(s): the canonical page, plus the `/{defaultLocale}/` alias when emitted.
 * @example
 * ```ts
-* await renderInstance(ctx, instance, { assets: "", template: null }, false);
+* await renderInstance(ctx, instance, shell, false);
 * ```
 */
 async function renderInstance(ctx, instance, shell, reuse) {
@@ -5135,20 +5219,31 @@ async function renderInstance(ctx, instance, shell, reuse) {
 	};
 	const html = shell.template === null ? renderDocument(parts) : fillTemplate(shell.template, parts);
 	await writeDocument(ctx.config.outDir, entry, params, html);
-	return {
+	const clientNavigable = definition._handlers.render !== void 0;
+	const pages = [{
 		url,
 		html,
 		data,
-		clientNavigable: definition._handlers.render !== void 0
-	};
+		clientNavigable
+	}];
+	if (locale === shell.defaultLocale && entry.pattern.includes("{lang:?}")) {
+		await writeDocumentAt(ctx.config.outDir, `${shell.defaultLocale}/${entry.toFile(params)}`, html);
+		pages.push({
+			url: `/${shell.defaultLocale}${url}`,
+			html,
+			data,
+			clientNavigable
+		});
+	}
+	return pages;
 }
 /**
 * Prepare the per-build {@link RenderShell} ONCE (O(1) per page): read the optional
 * shell `template` from disk when configured + present, and precompute the injected
 * asset tags. `template` is `null` when unset/missing (use the in-code shell).
 *
-* @param ctx - Plugin context (provides `config`, `state`).
-* @returns The shared shell wiring (asset tags + template-or-null) for every page.
+* @param ctx - Plugin context (provides `config`, `state`, `require`).
+* @returns The shared shell wiring (asset tags + template-or-null + default locale) for every page.
 * @example
 * ```ts
 * const shell = await prepareShell(ctx);
@@ -5159,7 +5254,8 @@ async function prepareShell(ctx) {
 	const template = typeof templatePath === "string" && (0, node_fs.existsSync)(templatePath) ? await (0, node_fs_promises.readFile)(templatePath, "utf8") : null;
 	return {
 		assets: buildAssetTags(ctx),
-		template
+		template,
+		defaultLocale: ctx.require(i18nPlugin).defaultLocale()
 	};
 }
 /**
@@ -5293,7 +5389,7 @@ async function renderPages(ctx, options) {
 	const byPattern = makeEntryMap(router);
 	if (!reuse) ctx.state.renderCache.clear();
 	const shell = await prepareShell(ctx);
-	const rendered = await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse));
+	const rendered = (await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse))).flat();
 	await writeDataSidecars(ctx, rendered, router.mode());
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {

package/dist/index.d.cts

@@ -1663,12 +1663,18 @@ type Config$3 = {
   injectAssets?: boolean; /** Directory copied verbatim into `outDir` (skipped silently if absent). Default `"public"`. */
   publicDir?: string;
   /**
-   * Emit `outDir/404.html`. `true` for the built-in default page, or
-   * `{ body }` to supply the page's literal HTML body content (written into the
-   * 404 page verbatim). Default `false`.
+   * Emit `outDir/404.html`. One of:
+   * - `true` — the built-in default page.
+   * - `{ body }` — literal HTML body content, wrapped in a minimal document shell.
+   * - `{ path }` — path to a complete HTML page file (resolved from the project
+   *   root), written out VERBATIM so the app owns the whole document (its own
+   *   `<head>`, asset links, and body).
+   *
+   * `path` takes precedence over `body` when both are set. Default `false`.
    */
   notFound?: boolean | {
     body?: string;
+    path?: string;
   }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
   localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
   clientEntry?: string;
@@ -3320,15 +3326,24 @@ declare function defineRoutes<T extends RouteMap>(routes: T): T;
  * directly: no `app.router` reference, no manual "bind", no module global, no
  * "not bound" guard, and no createApp ↔ routes cycle.
  *
+ * Pass `defaultLocale` so the builder serves that locale at BARE paths, matching the
+ * runtime `router.toUrl` (which reads the default locale from the i18n plugin):
+ * `toUrl("home", { lang: defaultLocale })` then resolves to `/` instead of
+ * `/{defaultLocale}/`. It is app-free, so the default locale cannot be inferred — the
+ * consumer supplies it (e.g. `createUrls(routes, "en")`). Omit it to keep every locale
+ * prefixed.
+ *
  * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+ * @param defaultLocale - The locale to serve bare (its `{lang:?}` prefix is omitted).
  * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
  * @example
  * ```ts
- * const url = createUrls(routes);
- * url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+ * const url = createUrls(routes, "en");
+ * url.toUrl("article", { lang: "en", slug: "hello" }); // "/hello/"
+ * url.toUrl("article", { lang: "ru", slug: "hello" }); // "/ru/hello/"
  * ```
  */
-declare function createUrls<T extends RouteMap>(routes: T): Urls<T>;
+declare function createUrls<T extends RouteMap>(routes: T, defaultLocale?: string): Urls<T>;
 //#endregion
 //#region src/plugins/router/index.d.ts
 /**

package/dist/index.d.mts

@@ -1663,12 +1663,18 @@ type Config$3 = {
   injectAssets?: boolean; /** Directory copied verbatim into `outDir` (skipped silently if absent). Default `"public"`. */
   publicDir?: string;
   /**
-   * Emit `outDir/404.html`. `true` for the built-in default page, or
-   * `{ body }` to supply the page's literal HTML body content (written into the
-   * 404 page verbatim). Default `false`.
+   * Emit `outDir/404.html`. One of:
+   * - `true` — the built-in default page.
+   * - `{ body }` — literal HTML body content, wrapped in a minimal document shell.
+   * - `{ path }` — path to a complete HTML page file (resolved from the project
+   *   root), written out VERBATIM so the app owns the whole document (its own
+   *   `<head>`, asset links, and body).
+   *
+   * `path` takes precedence over `body` when both are set. Default `false`.
    */
   notFound?: boolean | {
     body?: string;
+    path?: string;
   }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
   localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
   clientEntry?: string;
@@ -3320,15 +3326,24 @@ declare function defineRoutes<T extends RouteMap>(routes: T): T;
  * directly: no `app.router` reference, no manual "bind", no module global, no
  * "not bound" guard, and no createApp ↔ routes cycle.
  *
+ * Pass `defaultLocale` so the builder serves that locale at BARE paths, matching the
+ * runtime `router.toUrl` (which reads the default locale from the i18n plugin):
+ * `toUrl("home", { lang: defaultLocale })` then resolves to `/` instead of
+ * `/{defaultLocale}/`. It is app-free, so the default locale cannot be inferred — the
+ * consumer supplies it (e.g. `createUrls(routes, "en")`). Omit it to keep every locale
+ * prefixed.
+ *
  * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+ * @param defaultLocale - The locale to serve bare (its `{lang:?}` prefix is omitted).
  * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
  * @example
  * ```ts
- * const url = createUrls(routes);
- * url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+ * const url = createUrls(routes, "en");
+ * url.toUrl("article", { lang: "en", slug: "hello" }); // "/hello/"
+ * url.toUrl("article", { lang: "ru", slug: "hello" }); // "/ru/hello/"
  * ```
  */
-declare function createUrls<T extends RouteMap>(routes: T): Urls<T>;
+declare function createUrls<T extends RouteMap>(routes: T, defaultLocale?: string): Urls<T>;
 //#endregion
 //#region src/plugins/router/index.d.ts
 /**

package/dist/index.mjs

@@ -1219,10 +1219,31 @@ function contentApi(ctx) {
 */
 async function resolveArticle(ctx, slug, locale) {
 	const native = await ctx.provider.readArticle(slug, locale, locale, false);
-	if (native !== null) return native;
+	if (native !== null) return bareDefaultLocaleUrl(ctx, native);
 	const fallbackLocale = ctx.defaultLocale();
 	if (fallbackLocale === locale) return null;
-	return ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+	const fallback = await ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+	return fallback === null ? fallback : bareDefaultLocaleUrl(ctx, fallback);
+}
+/**
+* The default locale is served at BARE paths, so strip the leading `/{defaultLocale}`
+* from a default-locale article's `url` (`/en/hello/` → `/hello/`). Providers build
+* always-prefixed URLs (they have no i18n access); this is the single place the bare
+* default is applied, so article canonicals + feed GUIDs match the served URL.
+* Idempotent (a bare URL has no prefix to strip) and a no-op for non-default locales.
+*
+* @param ctx - Kernel-free domain context (i18n helpers).
+* @param article - The resolved article (mutated in place).
+* @returns The same article, with a bare `url` when it is the default locale.
+* @example
+* ```ts
+* bareDefaultLocaleUrl(ctx, { ...article, locale: "en", url: "/en/hello/" }).url; // "/hello/"
+* ```
+*/
+function bareDefaultLocaleUrl(ctx, article) {
+	const prefix = `/${ctx.defaultLocale()}`;
+	if (article.locale === ctx.defaultLocale() && article.url.startsWith(`${prefix}/`)) article.url = article.url.slice(prefix.length);
+	return article;
 }
 /**
 * Comparator sorting articles by frontmatter date descending (newest first),
@@ -2132,15 +2153,22 @@ function patternToUrlPattern(pattern, variant, langRegex) {
 * param is absent has its segment skipped entirely (no empty segment), so a missing
 * `{lang:?}` collapses cleanly instead of leaving a double slash.
 *
+* The default locale is served at BARE paths: when `defaultLocale` is given, the
+* optional `{lang:?}` segment is also skipped for it (so `{ lang: defaultLocale }`
+* resolves to `/…` while every other locale keeps its `/{locale}/…` prefix).
+*
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
+* @param defaultLocale - The locale served bare (its `{lang:?}` segment is omitted).
 * @returns The resolved relative URL string.
 * @example
 * ```ts
 * buildUrl("/{slug}/", { slug: "hello" }); // "/hello/"
+* buildUrl("/{lang:?}/", { lang: "en" }, "en"); // "/"
+* buildUrl("/{lang:?}/", { lang: "ru" }, "en"); // "/ru/"
 * ```
 */
-function buildUrl(pattern, params) {
+function buildUrl(pattern, params, defaultLocale) {
 	const out = [];
 	for (const segment of pattern.split("/")) {
 		const placeholder = parsePlaceholder(segment);
@@ -2150,6 +2178,7 @@ function buildUrl(pattern, params) {
 		}
 		const value = params[placeholder.name] ?? "";
 		if (placeholder.optional && value === "") continue;
+		if (placeholder.name === "lang" && placeholder.optional && value === defaultLocale) continue;
 		out.push(value);
 	}
 	return out.join("/");
@@ -2159,14 +2188,15 @@ function buildUrl(pattern, params) {
 *
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
+* @param defaultLocale - The locale served bare (forwarded to {@link buildUrl}).
 * @returns The output file path, e.g. `hello/index.html`.
 * @example
 * ```ts
 * buildFilePath("/{slug}/", { slug: "hello" });
 * ```
 */
-function buildFilePath(pattern, params) {
-	const cleanPath = buildUrl(pattern, params).replace(/^\//, "").replace(/\/$/, "");
+function buildFilePath(pattern, params, defaultLocale) {
+	const cleanPath = buildUrl(pattern, params, defaultLocale).replace(/^\//, "").replace(/\/$/, "");
 	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
 }
 /**
@@ -2195,15 +2225,16 @@ function buildMatchers(pattern, locales) {
 * pattern.
 *
 * @param pattern - The route pattern bound into the closure.
+* @param defaultLocale - The locale served bare (bound into the closure).
 * @returns A function mapping params to the resolved relative URL.
 * @example
 * ```ts
-* const toUrl = createToUrlFn("/{slug}/");
+* const toUrl = createToUrlFn("/{slug}/", "en");
 * toUrl({ slug: "x" }); // "/x/"
 * ```
 */
-function createToUrlFunction(pattern) {
-	return (params) => buildUrl(pattern, params);
+function createToUrlFunction(pattern, defaultLocale) {
+	return (params) => buildUrl(pattern, params, defaultLocale);
 }
 /**
 * Build the `toFile` closure for a route — resolves the output file path from
@@ -2212,15 +2243,16 @@ function createToUrlFunction(pattern) {
 *
 * @param pattern - The route pattern bound into the closure.
 * @param definition - The route definition carrying any `toFile` override.
+* @param defaultLocale - The locale served bare (bound into the closure).
 * @returns A function mapping params to the output file path.
 * @example
 * ```ts
-* const toFile = createToFileFn("/{slug}/", definition);
+* const toFile = createToFileFn("/{slug}/", definition, "en");
 * toFile({ slug: "x" }); // "x/index.html"
 * ```
 */
-function createToFileFunction(pattern, definition) {
-	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params);
+function createToFileFunction(pattern, definition, defaultLocale) {
+	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params, defaultLocale);
 }
 /**
 * Compile a single route definition into its `CompiledRoute` entry.
@@ -2237,8 +2269,8 @@ function createToFileFunction(pattern, definition) {
 function compileRoute(name, definition, input) {
 	const { pattern } = definition;
 	const matchers = buildMatchers(pattern, input.locales);
-	const toUrl = createToUrlFunction(pattern);
-	const toFile = createToFileFunction(pattern, definition);
+	const toUrl = createToUrlFunction(pattern, input.defaultLocale);
+	const toFile = createToFileFunction(pattern, definition, input.defaultLocale);
 	return {
 		name,
 		pattern,
@@ -2669,15 +2701,24 @@ function defineRoutes(routes) {
 * directly: no `app.router` reference, no manual "bind", no module global, no
 * "not bound" guard, and no createApp ↔ routes cycle.
 *
+* Pass `defaultLocale` so the builder serves that locale at BARE paths, matching the
+* runtime `router.toUrl` (which reads the default locale from the i18n plugin):
+* `toUrl("home", { lang: defaultLocale })` then resolves to `/` instead of
+* `/{defaultLocale}/`. It is app-free, so the default locale cannot be inferred — the
+* consumer supplies it (e.g. `createUrls(routes, "en")`). Omit it to keep every locale
+* prefixed.
+*
 * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+* @param defaultLocale - The locale to serve bare (its `{lang:?}` prefix is omitted).
 * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
 * @example
 * ```ts
-* const url = createUrls(routes);
-* url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+* const url = createUrls(routes, "en");
+* url.toUrl("article", { lang: "en", slug: "hello" }); // "/hello/"
+* url.toUrl("article", { lang: "ru", slug: "hello" }); // "/ru/hello/"
 * ```
 */
-function createUrls(routes) {
+function createUrls(routes, defaultLocale) {
 	return { 
 	/**
 	* Build a route's URL path from its name and params.
@@ -2688,13 +2729,13 @@ function createUrls(routes) {
 	* @throws {Error} If `name` is not present in the route map.
 	* @example
 	* ```ts
-	* url.toUrl("home", { lang: "en" }); // "/en/"
+	* url.toUrl("home", { lang: "ru" }); // "/ru/"
 	* ```
 	*/
 toUrl(name, params = {}) {
 		const definition = routes[name];
 		if (!definition) throw new Error(`[web] router: unknown route name "${String(name)}".\n  Check the name matches a key in the route map passed to createUrls.`);
-		return buildUrl(definition.pattern, params);
+		return buildUrl(definition.pattern, params, defaultLocale);
 	} };
 }
 //#endregion
@@ -3979,10 +4020,31 @@ function wrap(body) {
 	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>404 — Not Found</title></head><body>${body}</body></html>`;
 }
 /**
+* Resolve the 404 page HTML from `config.notFound`. Precedence: `path` (a
+* complete page file, read verbatim) > `body` (a fragment, wrapped in the
+* minimal shell) > the built-in default.
+*
+* @param notFound - The `config.notFound` value (already known to be truthy).
+* @returns The complete HTML document to write.
+* @example
+* ```ts
+* const html = await resolveHtml({ path: "src/404.html" });
+* ```
+*/
+async function resolveHtml(notFound) {
+	if (typeof notFound === "object" && notFound.path) try {
+		return await readFile(notFound.path, "utf8");
+	} catch (error) {
+		throw new Error(`build:not-found — could not read notFound.path "${notFound.path}"`, { cause: error });
+	}
+	return wrap(typeof notFound === "object" && notFound.body ? notFound.body : DEFAULT_BODY);
+}
+/**
 * Emits `outDir/404.html`. When `config.notFound` is `true`, writes the built-in
-* default page; when it is `{ body }`, writes the supplied HTML body content
-* verbatim inside the document shell. No-op (returns `null`) when `notFound` is
-* false/unset.
+* default page; `{ body }` writes the supplied HTML body content inside the
+* minimal document shell; `{ path }` writes the referenced HTML page file
+* verbatim (the app owns the whole document). No-op (returns `null`) when
+* `notFound` is false/unset.
 *
 * @param ctx - Plugin context (provides `config`, `log`).
 * @returns The written file path, or `null` when disabled.
@@ -3997,10 +4059,10 @@ async function generateNotFound(ctx) {
 		ctx.log.debug("build:not-found", { skipped: true });
 		return null;
 	}
-	const body = typeof notFound === "object" && notFound.body ? notFound.body : DEFAULT_BODY;
+	const html = await resolveHtml(notFound);
 	await mkdir(outDir, { recursive: true });
 	const file = path.join(outDir, "404.html");
-	await writeFile(file, wrap(body), "utf8");
+	await writeFile(file, html, "utf8");
 	ctx.log.debug("build:not-found", { path: file });
 	return { path: file };
 }
@@ -5083,7 +5145,24 @@ function renderBodyCached(ctx, instance, routeContext, data, reuse) {
 * ```
 */
 async function writeDocument(outDir, entry, params, html) {
-	const filePath = path.join(outDir, entry.toFile(params));
+	await writeDocumentAt(outDir, entry.toFile(params), html);
+}
+/**
+* Write an HTML document to an explicit relative path under `outDir`, creating parent
+* directories first. Backs both the canonical page path ({@link writeDocument}) and the
+* default-locale `/{defaultLocale}/…` alias copy ({@link renderInstance}).
+*
+* @param outDir - The build output directory.
+* @param relativeFile - The output file path relative to `outDir` (e.g. `en/index.html`).
+* @param html - The complete HTML document to write.
+* @returns A promise resolved once the file is written.
+* @example
+* ```ts
+* await writeDocumentAt("dist", "en/about/index.html", "<!DOCTYPE html>…");
+* ```
+*/
+async function writeDocumentAt(outDir, relativeFile, html) {
+	const filePath = path.join(outDir, relativeFile);
 	await mkdir(path.dirname(filePath), { recursive: true });
 	await writeFile(filePath, html, "utf8");
 }
@@ -5093,14 +5172,19 @@ async function writeDocument(outDir, entry, params, html) {
 * `<head>`/body → assemble the document (template fill or in-code shell) → write.
 * Uses the configured shell `template` when supplied, otherwise the in-code shell.
 *
+* The default locale is served at BARE paths, so each default-locale page on a
+* `{lang:?}` route is ALSO written to `/{defaultLocale}/…` — the SAME rendered HTML (its
+* canonical already points at the bare URL) — so an explicit `/{defaultLocale}/…` link
+* serves the page directly with no redirect. Both pages are returned so each gets a sidecar.
+*
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `has`).
 * @param instance - The concrete page instance to render.
-* @param shell - Per-build wiring shared across instances (asset tags + template).
+* @param shell - Per-build wiring shared across instances (asset tags + template + default locale).
 * @param reuse - Whether this run may reuse a cached body (incremental, no code change).
-* @returns The instance's URL, rendered HTML, loaded data, and client-nav flag.
+* @returns The rendered page(s): the canonical page, plus the `/{defaultLocale}/` alias when emitted.
 * @example
 * ```ts
-* await renderInstance(ctx, instance, { assets: "", template: null }, false);
+* await renderInstance(ctx, instance, shell, false);
 * ```
 */
 async function renderInstance(ctx, instance, shell, reuse) {
@@ -5122,20 +5206,31 @@ async function renderInstance(ctx, instance, shell, reuse) {
 	};
 	const html = shell.template === null ? renderDocument(parts) : fillTemplate(shell.template, parts);
 	await writeDocument(ctx.config.outDir, entry, params, html);
-	return {
+	const clientNavigable = definition._handlers.render !== void 0;
+	const pages = [{
 		url,
 		html,
 		data,
-		clientNavigable: definition._handlers.render !== void 0
-	};
+		clientNavigable
+	}];
+	if (locale === shell.defaultLocale && entry.pattern.includes("{lang:?}")) {
+		await writeDocumentAt(ctx.config.outDir, `${shell.defaultLocale}/${entry.toFile(params)}`, html);
+		pages.push({
+			url: `/${shell.defaultLocale}${url}`,
+			html,
+			data,
+			clientNavigable
+		});
+	}
+	return pages;
 }
 /**
 * Prepare the per-build {@link RenderShell} ONCE (O(1) per page): read the optional
 * shell `template` from disk when configured + present, and precompute the injected
 * asset tags. `template` is `null` when unset/missing (use the in-code shell).
 *
-* @param ctx - Plugin context (provides `config`, `state`).
-* @returns The shared shell wiring (asset tags + template-or-null) for every page.
+* @param ctx - Plugin context (provides `config`, `state`, `require`).
+* @returns The shared shell wiring (asset tags + template-or-null + default locale) for every page.
 * @example
 * ```ts
 * const shell = await prepareShell(ctx);
@@ -5146,7 +5241,8 @@ async function prepareShell(ctx) {
 	const template = typeof templatePath === "string" && existsSync(templatePath) ? await readFile(templatePath, "utf8") : null;
 	return {
 		assets: buildAssetTags(ctx),
-		template
+		template,
+		defaultLocale: ctx.require(i18nPlugin).defaultLocale()
 	};
 }
 /**
@@ -5280,7 +5376,7 @@ async function renderPages(ctx, options) {
 	const byPattern = makeEntryMap(router);
 	if (!reuse) ctx.state.renderCache.clear();
 	const shell = await prepareShell(ctx);
-	const rendered = await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse));
+	const rendered = (await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse))).flat();
 	await writeDataSidecars(ctx, rendered, router.mode());
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {

package/package.json

@@ -113,5 +113,5 @@
     "test:cli-e2e": "bun test src/plugins/cli/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.5.2"
+  "version": "1.6.0"
 }