@moku-labs/web 1.5.3 → 1.6.1

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
@@ -3616,15 +3636,28 @@ async function performNavigation(pathname, handlers) {
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
+* `beforeCapture` runs synchronously immediately before the swap — for the View
+* Transitions path that is before `startViewTransition` captures the "old" snapshot.
+* Scroll restoration belongs HERE, not in the router after the navigation: setting
+* the destination scroll at this moment means the old and new snapshots share the
+* same scrollY, so there is no scroll delta for the transition to animate and a
+* `position: sticky` header never un-pins (the cross-engine flicker, worst on WebKit).
+* Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
+* THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true);
+* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
-function runSwap(doSwap, viewTransitions) {
+function runSwap(doSwap, viewTransitions, beforeCapture) {
 	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const docWithVt = document;
-	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	beforeCapture?.();
+	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
 	else doSwap();
 }
 /**
@@ -3637,17 +3670,19 @@ function runSwap(doSwap, viewTransitions) {
 * @param swapSelector - CSS selector for the region to replace.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions);
+	}, viewTransitions, beforeCapture);
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -3702,7 +3737,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -3711,7 +3746,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -3755,9 +3790,10 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await navigate(url.pathname);
-				if (navEvent.navigationType === "traverse") navEvent.scroll();
-				else window.scrollTo(0, 0);
+				if (navEvent.navigationType === "traverse") {
+					await navigate(url.pathname, false);
+					navEvent.scroll();
+				} else await navigate(url.pathname);
 			}
 		});
 	};
@@ -3916,6 +3952,25 @@ function syncDataHead(route, routeContext) {
 function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
+	let pendingScrollToTop = true;
+	/**
+	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
+	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
+	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
+	* no pre-fetch scroll pause. `behavior: "instant"` defeats a page-level
+	* `scroll-behavior: smooth` that would otherwise animate the reset and re-create the
+	* delta. Traverse (back/forward) sets `pendingScrollToTop = false` and restores its
+	* saved position after the swap instead.
+	*
+	* @example
+	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
+	*/
+	const applyPendingScroll = () => {
+		if (pendingScrollToTop) window.scrollTo({
+			top: 0,
+			behavior: "instant"
+		});
+	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	*
@@ -3931,7 +3986,7 @@ function createSpaKernel(state, config, emit, deps) {
 		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		});
+		}, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -4026,7 +4081,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*
 		* @example
 		* ```ts
-		* runSwap(renderAndMount, resolved.viewTransitions);
+		* runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		* ```
 		*/
 		const renderAndMount = () => {
@@ -4034,7 +4089,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions);
+		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -4071,11 +4126,14 @@ function createSpaKernel(state, config, emit, deps) {
 	* navigation entry point (Navigation API, History, programmatic) goes through it.
 	*
 	* @param pathname - The destination pathname.
+	* @param scrollToTop - Whether the swap should scroll to top before its snapshot
+	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname) => {
+	const navigate = async (pathname, scrollToTop = true) => {
+		pendingScrollToTop = scrollToTop;
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
 		await performNavigation(pathname, handlers);
 	};
@@ -4424,10 +4482,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
@@ -5117,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");
 }
@@ -5127,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) {
@@ -5156,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);
@@ -5180,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()
 	};
 }
 /**
@@ -5314,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 {
@@ -10037,15 +10112,28 @@ async function performNavigation(pathname, handlers) {
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
+* `beforeCapture` runs synchronously immediately before the swap — for the View
+* Transitions path that is before `startViewTransition` captures the "old" snapshot.
+* Scroll restoration belongs HERE, not in the router after the navigation: setting
+* the destination scroll at this moment means the old and new snapshots share the
+* same scrollY, so there is no scroll delta for the transition to animate and a
+* `position: sticky` header never un-pins (the cross-engine flicker, worst on WebKit).
+* Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
+* THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true);
+* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
-function runSwap(doSwap, viewTransitions) {
+function runSwap(doSwap, viewTransitions, beforeCapture) {
 	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const docWithVt = document;
-	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	beforeCapture?.();
+	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
 	else doSwap();
 }
 /**
@@ -10058,17 +10146,19 @@ function runSwap(doSwap, viewTransitions) {
 * @param swapSelector - CSS selector for the region to replace.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions);
+	}, viewTransitions, beforeCapture);
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -10123,7 +10213,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -10132,7 +10222,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -10176,9 +10266,10 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await navigate(url.pathname);
-				if (navEvent.navigationType === "traverse") navEvent.scroll();
-				else window.scrollTo(0, 0);
+				if (navEvent.navigationType === "traverse") {
+					await navigate(url.pathname, false);
+					navEvent.scroll();
+				} else await navigate(url.pathname);
 			}
 		});
 	};
@@ -10337,6 +10428,25 @@ function syncDataHead(route, routeContext) {
 function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
+	let pendingScrollToTop = true;
+	/**
+	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
+	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
+	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
+	* no pre-fetch scroll pause. `behavior: "instant"` defeats a page-level
+	* `scroll-behavior: smooth` that would otherwise animate the reset and re-create the
+	* delta. Traverse (back/forward) sets `pendingScrollToTop = false` and restores its
+	* saved position after the swap instead.
+	*
+	* @example
+	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
+	*/
+	const applyPendingScroll = () => {
+		if (pendingScrollToTop) window.scrollTo({
+			top: 0,
+			behavior: "instant"
+		});
+	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	*
@@ -10352,7 +10462,7 @@ function createSpaKernel(state, config, emit, deps) {
 		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		});
+		}, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10447,7 +10557,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*
 		* @example
 		* ```ts
-		* runSwap(renderAndMount, resolved.viewTransitions);
+		* runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		* ```
 		*/
 		const renderAndMount = () => {
@@ -10455,7 +10565,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions);
+		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10492,11 +10602,14 @@ function createSpaKernel(state, config, emit, deps) {
 	* navigation entry point (Navigation API, History, programmatic) goes through it.
 	*
 	* @param pathname - The destination pathname.
+	* @param scrollToTop - Whether the swap should scroll to top before its snapshot
+	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname) => {
+	const navigate = async (pathname, scrollToTop = true) => {
+		pendingScrollToTop = scrollToTop;
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
 		await performNavigation(pathname, handlers);
 	};

package/dist/index.d.cts

@@ -3326,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

@@ -3326,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
@@ -5104,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");
 }
@@ -5114,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) {
@@ -5143,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);
@@ -5167,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()
 	};
 }
 /**
@@ -5301,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 {
@@ -10024,15 +10099,28 @@ async function performNavigation(pathname, handlers) {
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
+* `beforeCapture` runs synchronously immediately before the swap — for the View
+* Transitions path that is before `startViewTransition` captures the "old" snapshot.
+* Scroll restoration belongs HERE, not in the router after the navigation: setting
+* the destination scroll at this moment means the old and new snapshots share the
+* same scrollY, so there is no scroll delta for the transition to animate and a
+* `position: sticky` header never un-pins (the cross-engine flicker, worst on WebKit).
+* Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
+* THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true);
+* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
-function runSwap(doSwap, viewTransitions) {
+function runSwap(doSwap, viewTransitions, beforeCapture) {
 	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const docWithVt = document;
-	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	beforeCapture?.();
+	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
 	else doSwap();
 }
 /**
@@ -10045,17 +10133,19 @@ function runSwap(doSwap, viewTransitions) {
 * @param swapSelector - CSS selector for the region to replace.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions);
+	}, viewTransitions, beforeCapture);
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -10110,7 +10200,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -10119,7 +10209,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -10163,9 +10253,10 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await navigate(url.pathname);
-				if (navEvent.navigationType === "traverse") navEvent.scroll();
-				else window.scrollTo(0, 0);
+				if (navEvent.navigationType === "traverse") {
+					await navigate(url.pathname, false);
+					navEvent.scroll();
+				} else await navigate(url.pathname);
 			}
 		});
 	};
@@ -10324,6 +10415,25 @@ function syncDataHead(route, routeContext) {
 function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
+	let pendingScrollToTop = true;
+	/**
+	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
+	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
+	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
+	* no pre-fetch scroll pause. `behavior: "instant"` defeats a page-level
+	* `scroll-behavior: smooth` that would otherwise animate the reset and re-create the
+	* delta. Traverse (back/forward) sets `pendingScrollToTop = false` and restores its
+	* saved position after the swap instead.
+	*
+	* @example
+	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
+	*/
+	const applyPendingScroll = () => {
+		if (pendingScrollToTop) window.scrollTo({
+			top: 0,
+			behavior: "instant"
+		});
+	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	*
@@ -10339,7 +10449,7 @@ function createSpaKernel(state, config, emit, deps) {
 		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		});
+		}, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10434,7 +10544,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*
 		* @example
 		* ```ts
-		* runSwap(renderAndMount, resolved.viewTransitions);
+		* runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		* ```
 		*/
 		const renderAndMount = () => {
@@ -10442,7 +10552,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions);
+		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10479,11 +10589,14 @@ function createSpaKernel(state, config, emit, deps) {
 	* navigation entry point (Navigation API, History, programmatic) goes through it.
 	*
 	* @param pathname - The destination pathname.
+	* @param scrollToTop - Whether the swap should scroll to top before its snapshot
+	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname) => {
+	const navigate = async (pathname, scrollToTop = true) => {
+		pendingScrollToTop = scrollToTop;
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
 		await performNavigation(pathname, handlers);
 	};

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.3"
+  "version": "1.6.1"
 }