@moku-labs/web 1.6.1 → 1.7.0

package/dist/index.cjs

@@ -1,9 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_convention = require("./convention-krwh7Y6Q.cjs");
+const require_convention = require("./convention-BpDfzX7e.cjs");
 let _moku_labs_core = require("@moku-labs/core");
 let node_fs = require("node:fs");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
 let node_path = require("node:path");
 let node_path$1 = require_convention.__toESM(node_path, 1);
 node_path = require_convention.__toESM(node_path);
@@ -13,7 +14,6 @@ let preact_render_to_string = require("preact-render-to-string");
 let node_child_process = require("node:child_process");
 let node_readline = require("node:readline");
 let node_url = require("node:url");
-let node_os = require("node:os");
 let gray_matter = require("gray-matter");
 gray_matter = require_convention.__toESM(gray_matter, 1);
 let _shikijs_rehype = require("@shikijs/rehype");
@@ -41,7 +41,7 @@ let reading_time = require("reading-time");
 reading_time = require_convention.__toESM(reading_time, 1);
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
-const ERROR_PREFIX$15 = "[web]";
+const ERROR_PREFIX$16 = "[web]";
 /**
 * Creates the env plugin API surface mounted at `ctx.env`. Closes over
 * `ctx.state` ({@link EnvState}) and reads the frozen `resolved` / `publicMap`
@@ -85,7 +85,7 @@ function createEnvApi(ctx) {
 		*/
 		require(key) {
 			const value = resolved.get(key);
-			if (value === void 0) throw new Error(`${ERROR_PREFIX$15} env: required variable "${key}" is not defined.`);
+			if (value === void 0) throw new Error(`${ERROR_PREFIX$16} env: required variable "${key}" is not defined.`);
 			return value;
 		},
 		/**
@@ -152,7 +152,7 @@ function createEnvState() {
 /** Error message thrown by every frozen-map mutator. */
 const FROZEN_MESSAGE = "env: map is frozen and cannot be mutated";
 /** Error prefix for all resolution-pipeline failures. */
-const ERROR_PREFIX$14 = "[web]";
+const ERROR_PREFIX$15 = "[web]";
 /** The `Map` mutators redefined as throwers when a map is frozen. */
 const FROZEN_METHODS = [
 	"set",
@@ -221,8 +221,8 @@ function crossCheckPublicPrefix(config) {
 	const { schema, publicPrefix } = config;
 	for (const [key, spec] of Object.entries(schema)) {
 		const hasPrefix = key.startsWith(publicPrefix);
-		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$14} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
-		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$14} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
+		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$15} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
+		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$15} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
 	}
 }
 /**
@@ -304,7 +304,7 @@ function validateSchema(ctx) {
 	crossCheckPublicPrefix(config);
 	for (const [key, spec] of Object.entries(schema)) {
 		if (merged[key] === void 0 && spec.default !== void 0) merged[key] = spec.default;
-		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$14} env: required variable "${key}" is not defined by any provider or default.`);
+		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$15} env: required variable "${key}" is not defined by any provider or default.`);
 	}
 	populatePublicMap(schema, merged, state.publicMap);
 	populateResolved(merged, state.resolved);
@@ -912,7 +912,7 @@ const createCore = coreConfig.createCore;
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
-const ERROR_PREFIX$13 = "[web]";
+const ERROR_PREFIX$14 = "[web]";
 /**
 * Validates the resolved i18n config (fail-fast at `createApp`). Throws when
 * `locales` is empty or when `defaultLocale` is not a member of `locales`.
@@ -928,8 +928,8 @@ const ERROR_PREFIX$13 = "[web]";
 */
 function validateI18nConfig(ctx) {
 	const { locales, defaultLocale } = ctx.config;
-	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$13} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
-	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$13} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
+	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$14} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
+	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$14} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
 }
 /**
 * Creates the i18n plugin API surface — locale registry accessors plus the
@@ -1419,6 +1419,15 @@ function createContentApi(ctx) {
 		* suppressed and throws the SAME not-found error (drafts indistinguishable from
 		* missing); in development and test drafts load normally.
 		*
+		* Cache-first: when a preceding `loadAll()` (or earlier `load()`) already resolved +
+		* rendered this `(slug, locale)`, the cached Article (full html included) is returned
+		* without re-running the Markdown/Shiki pipeline — during a full build every
+		* per-article route loader would otherwise re-render an article `loadAll()` just
+		* rendered. Draft semantics are preserved: in production `loadAll()` filters drafts
+		* out BEFORE caching and the production `load()` path throws before caching, so a
+		* production cache hit is never a draft; misses fall through to a fresh resolve,
+		* which suppresses drafts exactly as before.
+		*
 		* @param slug - Article directory name.
 		* @param locale - Requested locale code.
 		* @returns The resolved Article.
@@ -1430,6 +1439,8 @@ function createContentApi(ctx) {
 		* ```
 		*/
 		async load(slug, locale) {
+			const cached = ctx.state.articles.get(locale)?.get(slug);
+			if (cached !== void 0) return cached;
 			const article = await resolveArticle(ctx, slug, locale);
 			if (article === null) throw articleNotFound(slug, locale);
 			if (ctx.global.stage === "production" && article.computed.status === "draft") throw articleNotFound(slug, locale);
@@ -1610,7 +1621,7 @@ const contentPlugin = createPlugin$1("content", {
 //#endregion
 //#region src/plugins/site/api.ts
 /** Error prefix for all site lifecycle/validation failures. */
-const ERROR_PREFIX$12 = "[web]";
+const ERROR_PREFIX$13 = "[web]";
 /** URL protocols that qualify a parsed URL as an absolute http/https URL. */
 const HTTP_PROTOCOLS = new Set(["http:", "https:"]);
 /**
@@ -1709,8 +1720,8 @@ function isAbsoluteUrl(value) {
 * ```
 */
 function validateSiteConfig(ctx) {
-	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$12} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
-	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$12} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
+	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$13} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
+	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$13} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
 }
 /**
 * Creates the site plugin API surface — read-only accessors over frozen config
@@ -1892,21 +1903,42 @@ function bySpecificity(a, b) {
 	return dynamicSegmentCount(a.pattern) - dynamicSegmentCount(b.pattern);
 }
 /**
+* Decode a captured group's percent-escapes so params round-trip with
+* `buildUrl`'s encoding (matchers run against the encoded `location.pathname`).
+* Falls back to the raw text on malformed escapes (never throw mid-match).
+*
+* @param value - The raw captured segment text (possibly percent-encoded).
+* @returns The decoded param value, or the raw text on malformed escapes.
+* @example
+* ```ts
+* decodeGroupValue("c%23%20tips"); // "c# tips"
+* ```
+*/
+function decodeGroupValue(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+/**
 * Extract named groups from a `URLPattern` match result, dropping numeric/regex
 * group keys and `undefined` values so only declared, present params remain.
+* Each value is percent-DECODED ({@link decodeGroupValue}) back to the literal
+* value `buildUrl` was given.
 *
 * @param groups - The `URLPatternResult.pathname.groups` object.
 * @returns A clean record of named params.
 * @example
 * ```ts
-* extractGroups({ slug: "hello", "0": "x" }); // { slug: "hello" }
+* extractGroups({ slug: "hello%20there", "0": "x" }); // { slug: "hello there" }
 * ```
 */
 function extractGroups(groups) {
 	const params = {};
 	for (const [key, value] of Object.entries(groups)) {
 		if (/^\d+$/.test(key)) continue;
-		if (value !== void 0) params[key] = value;
+		if (value !== void 0) params[key] = decodeGroupValue(value);
 	}
 	return params;
 }
@@ -2049,7 +2081,7 @@ function matchRoute(compiled, pathname) {
 //#endregion
 //#region src/plugins/router/builders/compile.ts
 /** Shared `[web]` error prefix for router validation failures. */
-const ERROR_PREFIX$11 = "[web] router";
+const ERROR_PREFIX$12 = "[web] router";
 /** Maximum number of optional `{lang:?}` segments a single pattern may declare. */
 const MAX_LANG_SEGMENTS = 1;
 /**
@@ -2109,9 +2141,9 @@ function hasValidLangCount(pattern) {
 * ```
 */
 function assertRouteValid(name, pattern) {
-	if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern must start with "/" (got "${pattern}").`);
-	if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
-	if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
+	if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$12}: route "${name}" pattern must start with "/" (got "${pattern}").`);
+	if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$12}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
+	if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$12}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
 }
 /**
 * Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
@@ -2127,7 +2159,7 @@ function assertRouteValid(name, pattern) {
 */
 function validateRoutes(routes) {
 	const names = Object.keys(routes);
-	if (names.length === 0) throw new Error(`${ERROR_PREFIX$11}: route map is empty.\n  Register at least one route via pluginConfigs.router.routes.`);
+	if (names.length === 0) throw new Error(`${ERROR_PREFIX$12}: route map is empty.\n  Register at least one route via pluginConfigs.router.routes.`);
 	for (const name of names) assertRouteValid(name, routes[name]?.pattern ?? "");
 }
 /**
@@ -2161,27 +2193,22 @@ function patternToUrlPattern(pattern, variant, langRegex) {
 	return out.join("/");
 }
 /**
-* Build a URL from a pattern and params (substitutes `{param}` / `{param:?}`).
-* Walks segment-by-segment (no backtracking regex). An optional placeholder whose
-* 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).
+* Substitute a pattern's placeholders one `/`-segment at a time (no backtracking
+* regex), passing each value through `encodeValue` — percent-encoding for
+* {@link buildUrl}, identity for {@link buildFilePath}. An absent optional segment
+* collapses (no double slash), as does `{lang:?}` for the bare `defaultLocale`.
 *
 * @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.
+* @param encodeValue - Encoder applied to each substituted param value.
+* @returns The resolved relative path string.
 * @example
 * ```ts
-* buildUrl("/{slug}/", { slug: "hello" }); // "/hello/"
-* buildUrl("/{lang:?}/", { lang: "en" }, "en"); // "/"
-* buildUrl("/{lang:?}/", { lang: "ru" }, "en"); // "/ru/"
+* substitutePattern("/{slug}/", { slug: "a b" }, undefined, encodeURIComponent); // "/a%20b/"
 * ```
 */
-function buildUrl(pattern, params, defaultLocale) {
+function substitutePattern(pattern, params, defaultLocale, encodeValue) {
 	const out = [];
 	for (const segment of pattern.split("/")) {
 		const placeholder = parsePlaceholder(segment);
@@ -2192,24 +2219,48 @@ function buildUrl(pattern, params, defaultLocale) {
 		const value = params[placeholder.name] ?? "";
 		if (placeholder.optional && value === "") continue;
 		if (placeholder.name === "lang" && placeholder.optional && value === defaultLocale) continue;
-		out.push(value);
+		out.push(encodeValue(value));
 	}
 	return out.join("/");
 }
 /**
+* Build a URL from a pattern and params (substitutes `{param}` / `{param:?}`;
+* segment walk in {@link substitutePattern}). Substituted values are
+* percent-encoded so reserved characters (`#`, `?`, `&`, spaces, …) cannot
+* truncate the path or break the sitemap XML, and the URL round-trips through
+* the matchers (`extractGroups` decodes captures back).
+*
+* @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: "a & b" }); // "/a%20%26%20b/"
+* buildUrl("/{lang:?}/", { lang: "en" }, "en"); // "/"
+* buildUrl("/{lang:?}/", { lang: "ru" }, "en"); // "/ru/"
+* ```
+*/
+function buildUrl(pattern, params, defaultLocale) {
+	return substitutePattern(pattern, params, defaultLocale, encodeURIComponent);
+}
+/**
 * Build an output file path from a pattern and params (always `…/index.html`).
+* Param values stay LITERAL: servers decode the encoded request path before
+* filesystem lookup, so on-disk names carry the decoded text.
 *
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
-* @param defaultLocale - The locale served bare (forwarded to {@link buildUrl}).
+* @param defaultLocale - The locale served bare (its `{lang:?}` segment is omitted).
 * @returns The output file path, e.g. `hello/index.html`.
 * @example
 * ```ts
-* buildFilePath("/{slug}/", { slug: "hello" });
+* buildFilePath("/{slug}/", { slug: "hello" }); // "hello/index.html"
+* buildFilePath("/{tag}/", { tag: "a & b" }); // "a & b/index.html"
 * ```
 */
 function buildFilePath(pattern, params, defaultLocale) {
-	const cleanPath = buildUrl(pattern, params, defaultLocale).replace(/^\//, "").replace(/\/$/, "");
+	const cleanPath = substitutePattern(pattern, params, defaultLocale, (value) => value).replace(/^\//, "").replace(/\/$/, "");
 	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
 }
 /**
@@ -2331,7 +2382,7 @@ function compileRoutes(input) {
 * `manifest`. Returns values/copies, never the raw `ctx.state` reference (spec/11 §2.4).
 */
 /** Error prefix for router API failures. */
-const ERROR_PREFIX$10 = "[web] router";
+const ERROR_PREFIX$11 = "[web] router";
 /**
 * Validate a route map and compile it into the matcher table on `ctx.state`,
 * resolving the global render `mode` + site base URL + i18n locales at call time.
@@ -2369,7 +2420,7 @@ function registerRoutes(ctx, routes) {
 * ```
 */
 function readTable(state) {
-	if (state.table === null) throw new Error(`${ERROR_PREFIX$10}: routes not registered.\n  Set pluginConfigs.router.routes before app.start() / app.build.run().`);
+	if (state.table === null) throw new Error(`${ERROR_PREFIX$11}: routes not registered.\n  Set pluginConfigs.router.routes before app.start() / app.build.run().`);
 	return state.table;
 }
 /**
@@ -2453,7 +2504,7 @@ function createApi$5(ctx) {
 		*/
 		toUrl(routeName, params) {
 			const entry = readTable(state).byName.get(routeName);
-			if (!entry) throw new Error(`${ERROR_PREFIX$10}: unknown route name "${routeName}".\n  Check the name matches a key in the route map registered via pluginConfigs.router.routes.`);
+			if (!entry) throw new Error(`${ERROR_PREFIX$11}: unknown route name "${routeName}".\n  Check the name matches a key in the route map registered via pluginConfigs.router.routes.`);
 			return entry.toUrl(params);
 		},
 		/**
@@ -3012,8 +3063,11 @@ function resolveImage(image, site) {
 }
 /**
 * Build the per-locale `hreflang` alternates for a route, plus the `x-default`
-* fallback (the route's URL with no `lang` override). Each alternate URL is the
-* route's canonical URL for that locale, absolutized against the site base URL.
+* fallback (the route's URL with `lang` STRIPPED, i.e. the bare default-locale
+* URL). Each alternate URL is the route's canonical URL for that locale,
+* absolutized against the site base URL. Stripping `lang` — rather than keeping
+* the page's own locale — keeps the x-default href byte-identical across every
+* locale variant of the route, as the hreflang spec requires.
 *
 * @param locales - The supported locale codes (drives the alternate set).
 * @param route - The resolved route descriptor (provides `name` + `params`).
@@ -3029,7 +3083,9 @@ function buildHreflangAlternates(locales, route, router, site) {
 			lang: locale
 		})));
 	});
-	const xDefaultHref = site.canonical(router.toUrl(route.name, { ...route.params }));
+	const bareParams = { ...route.params };
+	delete bareParams.lang;
+	const xDefaultHref = site.canonical(router.toUrl(route.name, bareParams));
 	alternates.push(hreflang(X_DEFAULT, xDefaultHref));
 	return alternates;
 }
@@ -3206,7 +3262,7 @@ function serializeHead(elements) {
 * it to a string. It holds no resource and caches no subscription.
 */
 /** Error prefix for head API invariant failures. */
-const ERROR_PREFIX$9 = "[web] head";
+const ERROR_PREFIX$10 = "[web] head";
 /**
 * Read the normalized defaults, asserting the post-`onInit` invariant (the slot is
 * `null` only before `onInit` assigns it, which cannot occur at render time).
@@ -3220,7 +3276,7 @@ const ERROR_PREFIX$9 = "[web] head";
 * ```
 */
 function readDefaults(state) {
-	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$9}: defaults accessed before onInit normalized them.`);
+	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$10}: defaults accessed before onInit normalized them.`);
 	return state.defaults;
 }
 /**
@@ -3288,7 +3344,7 @@ function createApi$4(ctx) {
 //#endregion
 //#region src/plugins/head/config.ts
 /** Error prefix for all head config-validation failures. */
-const ERROR_PREFIX$8 = "[web] head";
+const ERROR_PREFIX$9 = "[web] head";
 /** The allowed `twitterCard` literals (also the runtime guard set). */
 const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
 /**
@@ -3315,8 +3371,8 @@ const defaultConfig$3 = { twitterCard: "summary_large_image" };
 * ```
 */
 function validateHeadConfig(config) {
-	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$8}: titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
-	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$8}: twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
+	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$9}: titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
+	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$9}: twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
 }
 /**
 * Validate then build the frozen, normalized {@link HeadDefaults} snapshot read by
@@ -3443,14 +3499,16 @@ const JS_ENTRY_CANDIDATES = [
 /**
 * The default bundler runner — adapts the built-in `Bun.build`.
 *
-* @param options - Entry/outdir/minify settings forwarded to `Bun.build`.
+* @param options - Entry/outdir/minify/splitting/target settings forwarded to `Bun.build`.
 * @param options.entrypoints - Entry files for this build.
 * @param options.outdir - Output directory.
 * @param options.minify - Whether to minify.
+* @param options.splitting - Whether to split dynamic imports into lazy chunks.
+* @param options.target - The bundling target platform.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser" });
 * ```
 */
 async function defaultRunner(options) {
@@ -3519,7 +3577,9 @@ function normalizeAssetPath(absolutePath, outDir) {
 }
 /**
 * Run one bundler pass for a single asset kind and record the hashed output
-* paths under `state.buildCache` keyed by the original entry basename.
+* paths under `state.buildCache` keyed by the original entry basename. Lazy
+* split chunks are emitted to disk but excluded from the recorded manifest
+* (they must never be embedded as eager `<script>` tags).
 *
 * @param ctx - The phase context (state + log).
 * @param runner - The bundler runner to invoke.
@@ -3538,11 +3598,16 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 	const result = await runner({
 		entrypoints,
 		outdir,
-		minify
+		minify,
+		splitting: true,
+		target: "browser"
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
-	for (const output of result.outputs) hashed[node_path$1.default.basename(output.path)] = normalizeAssetPath(output.path, outDir);
+	for (const output of result.outputs) {
+		if (output.kind === "chunk") continue;
+		hashed[node_path$1.default.basename(output.path)] = normalizeAssetPath(output.path, outDir);
+	}
 	ctx.state.buildCache.set(kind, hashed);
 	ctx.log.debug("build:bundle", {
 		kind,
@@ -3714,10 +3779,34 @@ function createFeedChannel(site, defaultLocale) {
 		author: { name: site.author() }
 	});
 }
+/** Matches a root-relative `src`/`href` attribute opening (`="/`), excluding protocol-relative `="//`. */
+const ROOT_RELATIVE_URL_ATTR = /\b(src|href)="\/(?!\/)/g;
+/**
+* Absolutize root-relative `src`/`href` URLs in rendered article HTML against the
+* site base URL. The content pipeline rewrites co-located images to root-relative
+* paths (`/<slug>/images/...`) — fine on the site, broken inside a feed, where
+* readers do not reliably resolve relative URLs. Protocol-relative (`//host/...`)
+* and already-absolute URLs are left untouched.
+*
+* @param html - The rendered article HTML.
+* @param baseUrl - The absolute site base URL (trailing slashes tolerated).
+* @returns The HTML with every root-relative URL made absolute.
+* @example
+* ```ts
+* absolutizeContentUrls('<img src="/post/images/a.webp">', "https://blog.dev");
+* // '<img src="https://blog.dev/post/images/a.webp">'
+* ```
+*/
+function absolutizeContentUrls(html, baseUrl) {
+	let base = baseUrl;
+	while (base.endsWith("/")) base = base.slice(0, -1);
+	return html.replaceAll(ROOT_RELATIVE_URL_ATTR, (_match, attribute) => `${attribute}="${base}/`);
+}
 /**
 * Append one article to the feed and return its canonical GUID. The canonical
 * URL is the article's single stable identity — it is the item's id, guid, and
-* link at once.
+* link at once. Item content is the rendered HTML with root-relative URLs
+* absolutized against the site base, so embedded assets resolve in feed readers.
 *
 * @param feed - The feed channel to append to (mutated in place).
 * @param article - The published article to add.
@@ -3736,7 +3825,7 @@ function addArticleItem(feed$1, article, site) {
 		guid: canonicalUrl,
 		link: canonicalUrl,
 		description: article.frontmatter.description,
-		content: article.html,
+		content: absolutizeContentUrls(article.html, site.url()),
 		date: new Date(article.frontmatter.date),
 		author: [{ name: article.frontmatter.author ?? site.author() }]
 	});
@@ -3851,10 +3940,14 @@ async function processImages(ctx, options = {}) {
 //#endregion
 //#region src/plugins/build/phases/locale-redirects.ts
 /**
-* @file build phase — locale-redirects. For each non-prefixed route path, emits a
+* @file build phase — locale-redirects. For each REQUIRED-`{lang}` route (whose bare,
+* locale-less path would otherwise 404 — pages writes only `/{locale}/…`), emits a
 * redirect HTML page (`<meta http-equiv="refresh">` + canonical `<link>`) at the
-* bare path that points at the default-locale-prefixed URL. Deliberately does NOT
-* emit a Cloudflare `_redirects` catch-all (an SSG infinite-loop trap). Gated by
+* bare path that points at the default-locale-prefixed URL. OPTIONAL-`{lang:?}`
+* routes get NO redirect: the default locale is served BARE, so the pages phase
+* already writes the real content page at the bare path (plus a `/{defaultLocale}/…`
+* alias) — a redirect there would overwrite content. Deliberately does NOT emit a
+* Cloudflare `_redirects` catch-all (an SSG infinite-loop trap). Gated by
 * `config.localeRedirects` (false/unset disables).
 *
 * When `head.defaultOgImage` is configured, each redirect page ALSO carries the
@@ -3906,6 +3999,12 @@ function pairRoutes(router) {
 * redirect is ever emitted. Removing `lang` yields the real lang-less file/URL
 * (`/`, `/about/`, `/{slug}/`) that must redirect to the default-locale URL.
 *
+* Only a REQUIRED-`{lang}` route produces a job. On an OPTIONAL-`{lang:?}` route the
+* compiled `toUrl` serves the default locale BARE (`toUrl({ lang: defaultLocale })`
+* equals the bare URL), so `target === bareUrl` → `null`. That is by design AND the
+* collision guard: the pages phase writes the default-locale content page at exactly
+* that bare file, and a redirect would overwrite it.
+*
 * @param entry - The compiled `TypedRoute` (owns `toFile`/`toUrl`).
 * @param raw - One raw parameter set from `generate()` (may be `null`/`undefined`).
 * @param defaultLocale - The default locale to redirect bare paths to.
@@ -4650,7 +4749,7 @@ function dataApi(ctx) {
 		* ```
 		*/
 		async write(entries, options) {
-			const { writeData } = await Promise.resolve().then(() => require("./writer-DV5hWB2i.cjs"));
+			const { writeData } = await Promise.resolve().then(() => require("./writer-JdhX1Wld.cjs"));
 			return writeData(ctx, entries, options);
 		},
 		/**
@@ -4928,29 +5027,44 @@ async function generateParameterSets(definition, locale, ctx) {
 * locale). The generate context is the spec `{ locale, require, has }`, so a
 * `.generate()` handler pulls sibling APIs the spec way.
 *
+* Instances are deduplicated by resolved output file: a route whose pattern has no
+* lang placeholder (or whose `generate()` params omit `lang`) resolves to the SAME
+* `toFile` path for EVERY locale — without the guard each locale's render races on
+* one output file and the shipped HTML's locale is nondeterministic. The default
+* locale is expanded FIRST, so a collapsed route keeps its default-locale instance.
+*
 * @param definition - The route definition from the manifest.
 * @param locales - Active locale codes from i18n.
+* @param defaultLocale - The i18n default locale (kept when locales collapse to one file).
 * @param byPattern - Pattern→compiled-`TypedRoute` map (see {@link makeEntryMap}).
 * @param ctx - Plugin context (provides `require`/`has` for the generate context).
-* @returns The flattened list of page instances for this route.
+* @returns The flattened, file-deduplicated list of page instances for this route.
 * @example
 * ```ts
-* await expandRoute(def, ["en"], byPattern, ctx);
+* await expandRoute(def, ["en"], "en", byPattern, ctx);
 * ```
 */
-async function expandRoute(definition, locales, byPattern, ctx) {
+async function expandRoute(definition, locales, defaultLocale, byPattern, ctx) {
 	const entry = resolveEntry(byPattern, definition);
 	const { name } = entry;
+	const orderedLocales = [defaultLocale, ...locales.filter((locale) => locale !== defaultLocale)];
 	const instances = [];
-	for (const locale of locales) {
+	const claimedFiles = /* @__PURE__ */ new Set();
+	for (const locale of orderedLocales) {
 		const parameterSets = await generateParameterSets(definition, locale, ctx);
-		for (const raw of parameterSets) instances.push({
-			definition,
-			entry,
-			name,
-			params: raw ?? {},
-			locale
-		});
+		for (const raw of parameterSets) {
+			const params = raw ?? {};
+			const file = entry.toFile(params);
+			if (claimedFiles.has(file)) continue;
+			claimedFiles.add(file);
+			instances.push({
+				definition,
+				entry,
+				name,
+				params,
+				locale
+			});
+		}
 	}
 	return instances;
 }
@@ -5260,20 +5374,22 @@ async function prepareShell(ctx) {
 }
 /**
 * Expand every manifest route into its concrete page instances across all locales
-* (delegating per-route expansion to {@link expandRoute}) and flatten the result.
+* (delegating per-route expansion — and per-route output-file deduplication — to
+* {@link expandRoute}) and flatten the result.
 *
 * @param manifest - The route definitions from `router.manifest()`.
 * @param locales - Active locale codes from i18n.
+* @param defaultLocale - The i18n default locale (kept when a route's locales collapse).
 * @param byPattern - Pattern→compiled-`TypedRoute` map (see {@link makeEntryMap}).
 * @param ctx - Plugin context (provides `require`/`has` for generate contexts).
 * @returns The flattened list of page instances to render.
 * @example
 * ```ts
-* const instances = await expandAllInstances(manifest, ["en"], byPattern, ctx);
+* const instances = await expandAllInstances(manifest, ["en"], "en", byPattern, ctx);
 * ```
 */
-async function expandAllInstances(manifest, locales, byPattern, ctx) {
-	return (await Promise.all(manifest.map((definition) => expandRoute(definition, locales, byPattern, ctx)))).flat();
+async function expandAllInstances(manifest, locales, defaultLocale, byPattern, ctx) {
+	return (await Promise.all(manifest.map((definition) => expandRoute(definition, locales, defaultLocale, byPattern, ctx)))).flat();
 }
 /**
 * Persist per-page client-data sidecars when the app opts into client navigation
@@ -5389,7 +5505,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))).flat();
+	const rendered = (await renderInBatches(await expandAllInstances(manifest, locales, shell.defaultLocale, 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 {
@@ -5464,7 +5580,22 @@ async function expandUrls(definition, entry, locales, ctx) {
 	return urls;
 }
 /**
-* Serialize a `<urlset>` sitemap document from a canonical URL set.
+* XML-escape a value for safe insertion into a text node (`& < > " '`). `&` is
+* escaped first so already-escaped entities are not double-escaped.
+*
+* @param raw - The unsafe string.
+* @returns The XML-escaped string.
+* @example
+* ```ts
+* escapeXml("https://blog.dev/a&b/"); // "https://blog.dev/a&amp;b/"
+* ```
+*/
+function escapeXml(raw) {
+	return raw.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+/**
+* Serialize a `<urlset>` sitemap document from a canonical URL set. Each `<loc>`
+* value is XML-escaped so slugs containing `&`/`<`/`>` cannot break the document.
 *
 * @param urls - The canonical (absolute) URLs.
 * @returns The serialized sitemap XML.
@@ -5474,7 +5605,7 @@ async function expandUrls(definition, entry, locales, ctx) {
 * ```
 */
 function serializeSitemap(urls) {
-	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.map((url) => `  <url><loc>${url}</loc></url>`).join("\n")}\n</urlset>\n`;
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.map((url) => `  <url><loc>${escapeXml(url)}</loc></url>`).join("\n")}\n</urlset>\n`;
 }
 /**
 * Index the compiled router entries by their URL pattern, so each manifest
@@ -5580,7 +5711,8 @@ async function generateSitemap(ctx) {
 	const locales = ctx.require(i18nPlugin).locales();
 	const router = ctx.require(routerPlugin);
 	const byPattern = indexRoutesByPattern(router);
-	const urls = (await collectRelativeUrls(router.manifest(), byPattern, locales, ctx)).map((relative) => site.canonical(relative));
+	const relativeUrls = await collectRelativeUrls(router.manifest(), byPattern, locales, ctx);
+	const urls = [...new Set(relativeUrls)].map((relative) => site.canonical(relative));
 	const xml = serializeSitemap(urls);
 	const robots = buildRobotsTxt(site);
 	await writeSitemapFiles(ctx.config.outDir, xml, robots);
@@ -5597,6 +5729,8 @@ async function generateSitemap(ctx) {
 * @file build plugin — pipeline driver. Sequences the fixed multi-phase build,
 * emits `build:phase` boundaries, and runs intra-phase work via `Promise.all`.
 */
+/** Error prefix for build pipeline runtime failures (spec/11 Part-3). */
+const ERROR_PREFIX$8 = "[web] build";
 /** Matches a Markdown source path (a content edit). */
 const MARKDOWN_PATH = /\.md$/;
 /** Matches a stylesheet path (a CSS edit — does not change rendered page bodies). */
@@ -5632,6 +5766,46 @@ function planIncrementalRebuild(changed) {
 	};
 }
 /**
+* Test whether a resolved path sits STRICTLY inside a resolved base directory —
+* equality does not count (the base itself is never "inside" itself).
+*
+* @param resolved - The resolved absolute candidate path.
+* @param baseResolved - The resolved absolute base directory.
+* @returns `true` when `resolved` is nested beneath `baseResolved`.
+* @example
+* ```ts
+* isStrictlyInside("/app/dist", "/app"); // true — but isStrictlyInside("/app", "/app") is false
+* ```
+*/
+function isStrictlyInside(resolved, baseResolved) {
+	return resolved !== baseResolved && resolved.startsWith(baseResolved + node_path$1.default.sep);
+}
+/**
+* Assert that `outDir` is a SAFE target for the clean phase's recursive force-delete,
+* defending against a misconfiguration (`outDir: "/"`, `"."`, `"~"`, a `..` escape)
+* that would otherwise wipe the filesystem root, the home directory, or the project
+* itself. Mirrors the deploy plugin's `assertWithinRoot` posture, tightened for
+* deletion: a target is safe only when it sits STRICTLY inside the project root
+* (never the root itself) or strictly inside the OS temp directory (a disposable
+* area, used by preview/test builds) — and is never the home directory.
+*
+* @param outDir - The configured output directory (relative or absolute).
+* @param root - The absolute project root relative paths resolve against.
+* @returns The resolved absolute output directory.
+* @throws {Error} `[web] build.outDir` when the resolved target is unsafe to delete.
+* @example
+* ```ts
+* assertSafeCleanTarget("./dist", process.cwd()); // "<cwd>/dist"
+* ```
+*/
+function assertSafeCleanTarget(outDir, root) {
+	const resolved = node_path$1.default.isAbsolute(outDir) ? node_path$1.default.resolve(outDir) : node_path$1.default.resolve(root, outDir);
+	const rootResolved = node_path$1.default.resolve(root);
+	const isHome = resolved === node_path$1.default.resolve((0, node_os.homedir)());
+	if ((isStrictlyInside(resolved, rootResolved) || isStrictlyInside(resolved, node_path$1.default.resolve((0, node_os.tmpdir)()))) && !isHome) return resolved;
+	throw new Error(`${ERROR_PREFIX$8}.outDir: ${JSON.stringify(outDir)} (resolves to ${JSON.stringify(resolved)}) is not a safe clean target.\n  The clean phase force-deletes outDir recursively, so it must sit strictly inside the project root ${JSON.stringify(rootResolved)} (or the OS temp directory) — never the filesystem root, your home directory, or the project root itself.\n  Point build.outDir at a directory inside the project, e.g. "./dist".`);
+}
+/**
 * The static ordered list of pipeline phase names.
 *
 * @example
@@ -5681,17 +5855,23 @@ async function withPhase(ctx, phase, work) {
 }
 /**
 * Reset the per-run state (manifest, buildCache, runId) and assign a fresh runId.
+* A clean run (no `skipClean`) also drops the OG image hash cache: the outDir wipe
+* deletes every `og/<slug>.png` the cache indexes, so honoring those warm entries
+* would skip rendering files that no longer exist. A `skipClean` (dev) run keeps
+* the cache — its PNGs survive on disk.
 *
 * @param ctx - The phase context whose `state` is reset.
+* @param options - The run options (only `skipClean` is consulted).
 * @example
 * ```ts
-* resetRun(ctx);
+* resetRun(ctx, options);
 * ```
 */
-function resetRun(ctx) {
+function resetRun(ctx, options) {
 	ctx.state.manifest = null;
 	ctx.state.buildCache = /* @__PURE__ */ new Map();
 	ctx.state.runId = `${Date.now()}-${(0, node_crypto.randomUUID)()}`;
+	if (!options?.skipClean) ctx.state.ogImageHashCache.clear();
 }
 /**
 * Report each rejected outcome from a settled output batch as a `build:outputs`
@@ -5753,7 +5933,7 @@ async function runOutputs(ctx) {
 */
 async function runPipeline(ctx, options) {
 	const started = Date.now();
-	resetRun(ctx);
+	resetRun(ctx, options);
 	const outDir = options?.outDir ?? ctx.config.outDir;
 	const phaseContext = {
 		...ctx,
@@ -5764,10 +5944,13 @@ async function runPipeline(ctx, options) {
 		}
 	};
 	const plan = planIncrementalRebuild(options?.changed);
-	if (!options?.skipClean) await (0, node_fs_promises.rm)(outDir, {
-		recursive: true,
-		force: true
-	});
+	if (!options?.skipClean) {
+		assertSafeCleanTarget(outDir, process.cwd());
+		await (0, node_fs_promises.rm)(outDir, {
+			recursive: true,
+			force: true
+		});
+	}
 	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
 	await withPhase(phaseContext, "bundle", () => bundle(phaseContext));
 	await Promise.all([withPhase(phaseContext, "content", () => loadContent(phaseContext, {
@@ -10063,6 +10246,23 @@ function isInternalLink(url) {
 	return url.origin === location.origin && !STATIC_ASSET_RE.test(url.pathname);
 }
 /**
+* The navigable path of a URL or Location: pathname plus query string. The query
+* is part of page identity (the kernel's `currentUrl` is pathname + search), so
+* same-page checks, history entries, fetches, and scroll keys must all carry it —
+* comparing pathnames alone would treat `/search?q=a` → `/search?q=b` as same-page
+* and the History fallback would drop the query from the address bar.
+*
+* @param target - The URL or Location to read.
+* @param target.pathname - The path component.
+* @param target.search - The query-string component (`""` when absent).
+* @returns The pathname + search string.
+* @example
+* pathWithSearch(new URL("https://x.dev/search?q=a")); // "/search?q=a"
+*/
+function pathWithSearch(target) {
+	return target.pathname + target.search;
+}
+/**
 * Save the current scroll position keyed by path (best-effort; ignores storage errors).
 *
 * @param path - The path to key the scroll position under.
@@ -10091,19 +10291,27 @@ function restoreScrollPosition(path) {
 * Fetch a page and hand its HTML to the handlers; on any error fall back to a
 * full browser navigation (`location.href = pathname`).
 *
+* When `signal` aborts (this navigation was superseded by a newer one) the
+* fetch is cancelled and NOTHING is applied: no swap (onEnd) and no fallback
+* reload — the live navigation owns the document from that point on.
+*
 * @param pathname - The destination pathname.
 * @param handlers - The navigation lifecycle callbacks.
+* @param signal - Aborts when this navigation is superseded (`navEvent.signal`).
 * @returns A promise that resolves once the swap (or fallback) is dispatched.
 * @example
-* await performNavigation("/about", handlers);
+* await performNavigation("/about", handlers, navEvent.signal);
 */
-async function performNavigation(pathname, handlers) {
+async function performNavigation(pathname, handlers, signal) {
 	handlers.onStart(pathname);
 	try {
-		const response = await fetch(pathname);
+		const response = await (signal ? fetch(pathname, { signal }) : fetch(pathname));
 		if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
-		handlers.onEnd(await response.text(), pathname);
+		const html = await response.text();
+		if (signal?.aborted) return;
+		handlers.onEnd(html, pathname);
 	} catch {
+		if (signal?.aborted) return;
 		handlers.onError();
 		location.href = pathname;
 	}
@@ -10142,23 +10350,29 @@ function runSwap(doSwap, viewTransitions, beforeCapture) {
 * inside the same transition frame (after the DOM mutation) so component
 * re-mounting is captured by the transition snapshot.
 *
+* Returns whether the swap was dispatched: `false` when either document lacks
+* the `swapSelector` region, so the caller can fall back to a full navigation
+* instead of finishing the SPA nav against an un-swapped body.
+*
 * @param doc - The fetched document (DOMParser-parsed) holding the new region.
 * @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).
+* @returns `true` when the swap was dispatched, `false` when either document lacks the region.
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
 function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
-	if (!newContent || !currentContent) return;
+	if (!newContent || !currentContent) return false;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
 	}, viewTransitions, beforeCapture);
+	return true;
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -10192,7 +10406,20 @@ function resolveClickTarget(event) {
 * @example
 * const dispose = attachHistoryFallback(handlers);
 */
-function attachHistoryFallback(handlers, navigate = (pathname) => performNavigation(pathname, handlers)) {
+function attachHistoryFallback(handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal)) {
+	let controller;
+	/**
+	* Supersede the in-flight navigation (if any) and mint the next one's abort signal.
+	*
+	* @returns The fresh navigation's abort signal.
+	* @example
+	* const signal = supersede();
+	*/
+	const supersede = () => {
+		controller?.abort();
+		controller = new AbortController();
+		return controller.signal;
+	};
 	/**
 	* Intercept an internal-link click and run a History-API navigation.
 	*
@@ -10203,17 +10430,18 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	const onClick = (event) => {
 		const url = resolveClickTarget(event);
 		if (!url) return;
+		if (url.pathname === location.pathname && url.hash) return;
 		event.preventDefault();
-		if (url.pathname === location.pathname) {
+		if (pathWithSearch(url) === pathWithSearch(location)) {
 			window.scrollTo({
 				top: 0,
 				behavior: "smooth"
 			});
 			return;
 		}
-		saveScrollPosition(location.pathname);
-		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).catch(() => {});
+		saveScrollPosition(pathWithSearch(location));
+		history.pushState({ scrollY: 0 }, "", pathWithSearch(url));
+		navigate(pathWithSearch(url), true, supersede()).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -10222,7 +10450,11 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		const path = pathWithSearch(location);
+		const signal = supersede();
+		navigate(path, false, signal).then(() => {
+			if (!signal.aborted) restoreScrollPosition(path);
+		}).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -10241,7 +10473,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 * @example
 * const dispose = attachNavigationApi(navigation, handlers);
 */
-function attachNavigationApi(navigation, handlers, navigate = (pathname) => performNavigation(pathname, handlers)) {
+function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal)) {
 	/**
 	* Handle a `navigate` event: classify, then intercept with fetch-and-swap.
 	*
@@ -10253,7 +10485,7 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		const url = new URL(navEvent.destination.url);
 		if (!navEvent.canIntercept || navEvent.hashChange || navEvent.downloadRequest) return;
 		if (!isInternalLink(url)) return;
-		if (url.pathname === location.pathname) {
+		if (pathWithSearch(url) === pathWithSearch(location)) {
 			navEvent.intercept({ handler: () => {
 				window.scrollTo({
 					top: 0,
@@ -10267,9 +10499,9 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 			scroll: "manual",
 			handler: async () => {
 				if (navEvent.navigationType === "traverse") {
-					await navigate(url.pathname, false);
-					navEvent.scroll();
-				} else await navigate(url.pathname);
+					await navigate(pathWithSearch(url), false, navEvent.signal);
+					if (!navEvent.signal.aborted) navEvent.scroll();
+				} else await navigate(pathWithSearch(url), true, navEvent.signal);
 			}
 		});
 	};
@@ -10433,22 +10665,33 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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.
+	* no pre-fetch scroll pause. Traverse (back/forward) sets `pendingScrollToTop = false`
+	* and restores its saved position after the swap instead.
+	*
+	* Scroll behaviour: `"instant"` ONLY when view transitions are enabled — that is what
+	* keeps scrollY=0 in the captured snapshot (a `scroll-behavior: smooth` would otherwise
+	* animate the reset and re-create the delta → sticky-header flicker). With view
+	* transitions OFF there is no snapshot to protect, so it honours the page's
+	* `scroll-behavior` (`"auto"` = use the CSS value, e.g. a smooth scroll-to-top on nav).
 	*
 	* @example
 	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
 	*/
 	const applyPendingScroll = () => {
-		if (pendingScrollToTop) window.scrollTo({
+		if (!pendingScrollToTop) return;
+		const behavior = resolved.viewTransitions ? "instant" : "auto";
+		window.scrollTo({
 			top: 0,
-			behavior: "instant"
+			behavior
 		});
 	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
+	* When the region cannot be swapped (either document lacks the swap selector)
+	* the SPA nav cannot complete — the head is already synced and the islands torn
+	* down, so finishing would leave the OLD body under a NEW URL with a `spa:navigated`
+	* claiming success. Fall back to a full browser navigation instead (mirroring
+	* {@link performNavigation}'s fetch-error fallback).
 	*
 	* @param html - The fetched page HTML.
 	* @param pathname - The destination pathname.
@@ -10459,10 +10702,14 @@ function createSpaKernel(state, config, emit, deps) {
 		const doc = new DOMParser().parseFromString(html, "text/html");
 		syncHead(deps.head, doc);
 		unmountPageSpecific(state, emit);
-		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
+		if (!swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		}, applyPendingScroll);
+		}, applyPendingScroll)) {
+			handleError();
+			location.href = pathname;
+			return;
+		}
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10542,13 +10789,16 @@ function createSpaKernel(state, config, emit, deps) {
 	*
 	* @param pathname - The destination pathname (recorded as the new current URL).
 	* @param resolvedRender - The inputs produced by {@link resolveDataRender}.
+	* @param signal - Aborts when this navigation is superseded (`navEvent.signal`).
 	* @example
 	* await commitDataRender("/en/world/", resolved);
 	*/
-	const commitDataRender = async (pathname, resolvedRender) => {
+	const commitDataRender = async (pathname, resolvedRender, signal) => {
+		if (signal?.aborted) return;
 		const { route, vnode, routeContext, region } = resolvedRender;
 		handleStart(pathname);
 		const { renderVNode } = await Promise.resolve().then(() => require("./render-DLZEOe4M.cjs"));
+		if (signal?.aborted) return;
 		syncDataHead(route, routeContext);
 		unmountPageSpecific(state, emit);
 		/**
@@ -10580,15 +10830,16 @@ function createSpaKernel(state, config, emit, deps) {
 	* to HTML-over-fetch.
 	*
 	* @param pathname - The destination pathname (search stripped for matching).
+	* @param signal - Aborts when this navigation is superseded (`navEvent.signal`).
 	* @returns `true` if the route was rendered from its data, else `false`.
 	* @example
 	* if (await tryDataRender("/en/world/")) return;
 	*/
-	const tryDataRender = async (pathname) => {
+	const tryDataRender = async (pathname, signal) => {
 		try {
 			const resolvedRender = await resolveDataRender(pathname);
 			if (resolvedRender === false) return false;
-			await commitDataRender(pathname, resolvedRender);
+			await commitDataRender(pathname, resolvedRender, signal);
 			return true;
 		} catch {
 			progress?.done();
@@ -10604,14 +10855,17 @@ function createSpaKernel(state, config, emit, deps) {
 	* @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.
+	* @param signal - Aborts when this navigation is superseded (`navEvent.signal`);
+	*   a superseded navigation never applies its swap (no stale last-write-wins).
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname, scrollToTop = true) => {
+	const navigate = async (pathname, scrollToTop = true, signal) => {
 		pendingScrollToTop = scrollToTop;
-		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
-		await performNavigation(pathname, handlers);
+		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname, signal)) return;
+		if (signal?.aborted) return;
+		await performNavigation(pathname, handlers, signal);
 	};
 	return {
 		/**
@@ -11212,9 +11466,12 @@ function defaultRehypePlugins() {
 * Clones the library default and additively allowlists the markup our custom
 * transforms emit: `class` values (`pull-quote`, `section-divider`,
 * `section-divider-ornament`) on `aside`/`div`/`span`, and the `loading`
-* attribute on `img`. `class`/`className`/`style` are allowlisted globally (`*`,
-* i.e. on every element) — not just on `pre`/`code`/`span` — so Shiki's inline
-* token colors survive the sanitize pass.
+* attribute on `img`. `class`/`className` are allowlisted globally (`*`, i.e.
+* on every element) so Shiki's class hooks survive the sanitize pass. `style`
+* is deliberately NOT global — CSS values are not sanitized, so a global
+* `style` allowlist would let untrusted content run overlay/exfiltration
+* styling; it is allowed only on `pre`/`code`, where Shiki places its
+* block-level theme background/foreground.
 *
 * @returns The extended, security-hardened sanitize schema.
 * @example
@@ -11245,8 +11502,7 @@ function buildSanitizeSchema() {
 			"*": [
 				...baseAttributes["*"] ?? [],
 				"className",
-				"class",
-				"style"
+				"class"
 			],
 			aside: [
 				...baseAttributes.aside ?? [],