@moku-labs/web 1.6.2 → 1.8.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
@@ -3430,7 +3486,9 @@ const headPlugin = createPlugin$1("head", {
 //#region src/plugins/build/phases/bundle.ts
 /**
 * @file build phase 1 — bundle. Runs `Bun.build` for CSS and JS separately into
-* outDir (honoring `config.minify`); caches hashed asset paths for the pages phase.
+* outDir (honoring `config.minify`) with content-hashed output naming; caches the
+* fingerprinted asset paths for the pages phase and the complete output list for
+* the cache-headers phase.
 */
 /** Conventional CSS entry candidates (project-relative). */
 const CSS_ENTRY_CANDIDATES = ["src/client/styles.css", "src/styles/main.css"];
@@ -3441,16 +3499,38 @@ const JS_ENTRY_CANDIDATES = [
 	"src/main.ts"
 ];
 /**
+* `Bun.build` output naming with a content hash in EVERY filename (entry points
+* included — Bun's default only hashes chunks/assets). A bundle's URL therefore
+* changes whenever its bytes change, which is what lets the cache-headers phase
+* mark each bundle immutable: a CDN/browser may cache it forever, and a deploy
+* that changes the code ships a NEW URL instead of fighting a stale cached copy.
+* Pages always embed bundle URLs via the `state.buildCache` manifest, so hashed
+* names flow through with no app-side changes (hardcoded asset URLs must move to
+* the `<!--moku:assets-->` placeholders). Chunk naming keeps Bun's default
+* `chunk-` prefix (chunks were already hash-only named).
+*/
+const FINGERPRINT_NAMING = {
+	entry: "[dir]/[name]-[hash].[ext]",
+	chunk: "chunk-[hash].[ext]",
+	asset: "[name]-[hash].[ext]"
+};
+/**
 * 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/naming 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.
+* @param options.naming - Output naming templates (content-hashed filenames).
+* @param options.naming.entry - Naming template for entry-point outputs.
+* @param options.naming.chunk - Naming template for lazy split chunks.
+* @param options.naming.asset - Naming template for additional emitted assets.
 * @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", naming: FINGERPRINT_NAMING });
 * ```
 */
 async function defaultRunner(options) {
@@ -3519,7 +3599,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,12 +3620,19 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 	const result = await runner({
 		entrypoints,
 		outdir,
-		minify
+		minify,
+		splitting: true,
+		target: "browser",
+		naming: FINGERPRINT_NAMING
 	});
 	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.state.buildCache.set(`${kind}:outputs`, result.outputs.map((output) => normalizeAssetPath(output.path, outDir)));
 	ctx.log.debug("build:bundle", {
 		kind,
 		count: result.outputs.length
@@ -3575,6 +3664,269 @@ async function bundle(ctx, options = {}) {
 	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
 }
 //#endregion
+//#region src/plugins/build/phases/asset-tags.ts
+/** Template placeholder for the injected asset tags (stylesheets + scripts). */
+const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
+/** Template placeholder for the injected stylesheet `<link>` tags ONLY. */
+const CSS_ASSETS_PLACEHOLDER = "<!--moku:assets:css-->";
+/** Template placeholder for the injected `<script>` tags ONLY. */
+const JS_ASSETS_PLACEHOLDER = "<!--moku:assets:js-->";
+/**
+* Read the bundle phase's fingerprinted asset manifest for one kind from
+* `state.buildCache` as a typed {@link BuildCacheEntry} (no `Map<string, unknown>`
+* reads at call sites).
+*
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The fingerprinted-path manifest entry, or an empty object when absent.
+* @example
+* ```ts
+* readManifest(ctx, "css"); // { "main.css": "assets/main-abc123.css" }
+* ```
+*/
+function readManifest(ctx, kind) {
+	const entry = ctx.state.buildCache.get(kind);
+	return entry && typeof entry === "object" ? entry : {};
+}
+/**
+* Read the bundle phase's COMPLETE output list for one kind (entries + lazy split
+* chunks, web paths relative to the publish root) from `state.buildCache`. Unlike
+* {@link readManifest} this includes chunks — it feeds the cache-headers phase's
+* per-file immutable rules, where every fingerprinted file counts, not just the
+* eagerly embedded entries.
+*
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The publish-root-relative output paths, or an empty array when absent.
+* @example
+* ```ts
+* readBundleOutputs(ctx, "js"); // ["assets/spa-abc123.js", "assets/chunk-9f8e.js"]
+* ```
+*/
+function readBundleOutputs(ctx, kind) {
+	const entry = ctx.state.buildCache.get(`${kind}:outputs`);
+	return Array.isArray(entry) ? entry : [];
+}
+/**
+* Render the stylesheet `<link>` tags for the fingerprinted CSS manifest.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The concatenated `<link rel="stylesheet">` tags (possibly `""`).
+* @example
+* ```ts
+* buildCssTags(ctx); // '<link rel="stylesheet" href="/assets/main-abc123.css">'
+* ```
+*/
+function buildCssTags(ctx) {
+	return Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`).join("");
+}
+/**
+* Render the module `<script>` tags for the fingerprinted JS manifest.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The concatenated `<script type="module">` tags (possibly `""`).
+* @example
+* ```ts
+* buildJsTags(ctx); // '<script type="module" src="/assets/spa-abc123.js"><\/script>'
+* ```
+*/
+function buildJsTags(ctx) {
+	return Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+}
+/**
+* Build the asset tag block from the fingerprinted manifests — both kinds by
+* default, or a single kind for the split `<!--moku:assets:css/js-->`
+* placeholders. Returns an empty string when `config.injectAssets === false`.
+* Asset paths are emitted as absolute (`/`-rooted) URLs.
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @param kind - Restrict the block to one asset kind; omit for stylesheets + scripts.
+* @returns The injected asset tags, or `""` when injection is disabled.
+* @example
+* ```ts
+* buildAssetTags(ctx);        // <link …><script …><\/script>
+* buildAssetTags(ctx, "css"); // <link …> only
+* ```
+*/
+function buildAssetTags(ctx, kind) {
+	if (ctx.config.injectAssets === false) return "";
+	if (kind === "css") return buildCssTags(ctx);
+	if (kind === "js") return buildJsTags(ctx);
+	return buildCssTags(ctx) + buildJsTags(ctx);
+}
+/**
+* Substitute every `<!--moku:assets-->` family placeholder in a complete HTML
+* document: the combined block, the CSS-only block, and the JS-only block. A
+* document without placeholders passes through byte-identical — substitution is
+* strictly opt-in for app-owned pages (the not-found page).
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @param html - The HTML document to substitute placeholders in.
+* @returns The document with all asset placeholders replaced.
+* @example
+* ```ts
+* substituteAssetPlaceholders(ctx, "<head><!--moku:assets:css--></head>");
+* ```
+*/
+function substituteAssetPlaceholders(ctx, html) {
+	return html.replaceAll(ASSETS_PLACEHOLDER, buildAssetTags(ctx)).replaceAll(CSS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "css")).replaceAll(JS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "js"));
+}
+/**
+* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
+* preserving the nested directory structure. Skips silently (returns `null`) when
+* the source directory does not exist.
+*
+* @param ctx - Plugin context (provides `config`, `log`).
+* @returns The copy result, or `null` when the public directory is absent.
+* @example
+* ```ts
+* const result = await copyPublic(ctx);
+* ```
+*/
+async function copyPublic(ctx) {
+	const from = ctx.config.publicDir ?? "public";
+	if (!(0, node_fs.existsSync)(from)) {
+		ctx.log.debug("build:public", {
+			skipped: true,
+			from
+		});
+		return null;
+	}
+	await (0, node_fs_promises.cp)(from, ctx.config.outDir, { recursive: true });
+	ctx.log.debug("build:public", {
+		from,
+		dest: ctx.config.outDir
+	});
+	return {
+		from: node_path$1.default.normalize(from),
+		copied: 1
+	};
+}
+//#endregion
+//#region src/plugins/build/phases/cache-headers.ts
+/**
+* @file build phase — cache-headers. Emits `outDir/_headers` (Cloudflare Pages
+* header rules) so the CDN/browser cache can never serve a stale file: every
+* fingerprinted bundle gets a per-file immutable rule (its URL changes with its
+* content, so caching it forever is safe), and every OTHER URL — pages, content
+* images, feeds, data sidecars: stable URLs whose bytes may change between
+* deploys — gets a catch-all revalidation rule (an unchanged file still answers
+* `304 Not Modified` via its ETag, so it is effectively cached; a changed file is
+* picked up immediately). The app's own `<publicDir>/_headers` rules are appended
+* AFTER the generated ones so the app can override them. Gated by
+* `config.cacheHeaders` (`false` disables; default on).
+*/
+/**
+* `Cache-Control` for fingerprinted bundles: their URL embeds a content hash, so
+* the bytes behind a given URL can never change — cache them for a year, immutably.
+*/
+const DEFAULT_ASSETS_CACHE = "public, max-age=31536000, immutable";
+/**
+* `Cache-Control` for everything else (stable URLs): always revalidate with the
+* origin. Unchanged files still serve from cache via a `304` ETag round-trip;
+* changed files are fetched fresh — never stale, still cheap.
+*/
+const DEFAULT_PAGES_CACHE = "public, max-age=0, must-revalidate";
+/**
+* Cloudflare Pages caps `_headers` at 100 rules and silently ignores the rest —
+* a site whose bundle count pushes past the cap needs a warning, not silence.
+*/
+const CLOUDFLARE_RULE_LIMIT = 100;
+/**
+* Resolve the two `Cache-Control` values from `config.cacheHeaders` (`true` or an
+* object — `false` never reaches here; the pipeline gates the phase off).
+*
+* @param cacheHeaders - The `config.cacheHeaders` value.
+* @returns The `assets` (fingerprinted bundles) + `pages` (everything else) values.
+* @example
+* ```ts
+* resolvePolicy(true); // { assets: DEFAULT_ASSETS_CACHE, pages: DEFAULT_PAGES_CACHE }
+* ```
+*/
+function resolvePolicy(cacheHeaders) {
+	const policy = typeof cacheHeaders === "object" ? cacheHeaders : {};
+	return {
+		assets: policy.assets ?? DEFAULT_ASSETS_CACHE,
+		pages: policy.pages ?? DEFAULT_PAGES_CACHE
+	};
+}
+/**
+* Compose the generated rule blocks: the catch-all revalidation rule FIRST, then
+* one immutable rule per fingerprinted bundle file. Cloudflare applies every
+* matching rule and comma-joins duplicate headers (it does NOT override), so each
+* per-file rule must detach the catch-all's `Cache-Control` (`! Cache-Control`)
+* before attaching its own — otherwise a bundle would be served with two joined,
+* contradictory `Cache-Control` values.
+*
+* @param files - The fingerprinted bundle web paths (publish-root-relative).
+* @param policy - The resolved `Cache-Control` values.
+* @param policy.assets - The value for fingerprinted bundles.
+* @param policy.pages - The catch-all value for everything else.
+* @returns The generated rule blocks, in emission order.
+* @example
+* ```ts
+* composeRules(["assets/main-abc123.css"], { assets: "…", pages: "…" });
+* ```
+*/
+function composeRules(files, policy) {
+	return [`/*\n  Cache-Control: ${policy.pages}`, ...files.map((file) => `/${file}\n  ! Cache-Control\n  Cache-Control: ${policy.assets}`)];
+}
+/**
+* Read the app's own `<publicDir>/_headers` SOURCE file (not the copy the public
+* phase may have placed in outDir — composing from the source keeps this phase
+* idempotent and independent of phase ordering). Returns `""` when absent.
+*
+* @param publicDir - The configured public directory (or the default).
+* @returns The app's `_headers` content, or `""` when the file does not exist.
+* @example
+* ```ts
+* const appRules = await readAppHeaders("public");
+* ```
+*/
+async function readAppHeaders(publicDir) {
+	const source = node_path$1.default.join(publicDir, "_headers");
+	if (!(0, node_fs.existsSync)(source)) return "";
+	return (0, node_fs_promises.readFile)(source, "utf8");
+}
+/**
+* Emits `outDir/_headers`: the generated cache rules (catch-all revalidation +
+* per-file immutable bundle rules) followed by the app's own
+* `<publicDir>/_headers` content. App rules come LAST so they can override a
+* generated header — note Cloudflare comma-joins duplicates, so an app rule that
+* re-sets a generated header must detach it first (`! Cache-Control`). Overwrites
+* the verbatim copy the public phase made, which is why this phase must run after
+* the outputs phase group.
+*
+* @param ctx - Plugin context (provides `state`, `config`, `log`).
+* @returns The written file path + generated rule count.
+* @example
+* ```ts
+* const result = await generateCacheHeaders(ctx);
+* ```
+*/
+async function generateCacheHeaders(ctx) {
+	const { outDir, publicDir, cacheHeaders } = ctx.config;
+	const policy = resolvePolicy(cacheHeaders);
+	const rules = composeRules([...readBundleOutputs(ctx, "css"), ...readBundleOutputs(ctx, "js")].toSorted(), policy);
+	const appHeaders = (await readAppHeaders(publicDir ?? "public")).trim();
+	const content = `${(appHeaders === "" ? rules : [...rules, appHeaders]).join("\n\n")}\n`;
+	if (rules.length > CLOUDFLARE_RULE_LIMIT) ctx.log.warn("build:cache-headers", {
+		rules: rules.length,
+		limit: CLOUDFLARE_RULE_LIMIT
+	});
+	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
+	const file = node_path$1.default.join(outDir, "_headers");
+	await (0, node_fs_promises.writeFile)(file, content, "utf8");
+	ctx.log.debug("build:cache-headers", {
+		path: file,
+		rules: rules.length
+	});
+	return {
+		path: file,
+		ruleCount: rules.length
+	};
+}
+//#endregion
 //#region src/plugins/build/phases/content.ts
 /**
 * @file build phase 2 — content. Delegates entirely to the content plugin via
@@ -3714,10 +4066,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 +4112,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 +4227,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 +4286,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.
@@ -4015,7 +4401,10 @@ async function generateLocaleRedirects(ctx) {
 //#region src/plugins/build/phases/not-found.ts
 /**
 * @file build phase — not-found. Emits `outDir/404.html` from configured route
-* content or a built-in default. Gated by `config.notFound` (false/unset disables).
+* content or a built-in default, substituting the `<!--moku:assets-->` family of
+* placeholders (the bundles are fingerprint-named, so an app-owned 404 page can
+* no longer hardcode a bundle URL). Gated by `config.notFound` (false/unset
+* disables).
 */
 /** The built-in default 404 page body when no custom route content is supplied. */
 const DEFAULT_BODY = "<h1>404</h1><p>The page you requested could not be found.</p>";
@@ -4055,11 +4444,13 @@ async function resolveHtml(notFound) {
 /**
 * Emits `outDir/404.html`. When `config.notFound` is `true`, writes the built-in
 * default page; `{ body }` writes the supplied HTML body content inside the
-* minimal document shell; `{ path }` writes the referenced HTML page file
-* verbatim (the app owns the whole document). No-op (returns `null`) when
-* `notFound` is false/unset.
+* minimal document shell; `{ path }` writes the referenced HTML page file (the
+* app owns the whole document). In every variant the `<!--moku:assets-->` /
+* `<!--moku:assets:css-->` / `<!--moku:assets:js-->` placeholders are substituted
+* with the fingerprinted bundle tags — a page without placeholders passes through
+* byte-for-byte. No-op (returns `null`) when `notFound` is false/unset.
 *
-* @param ctx - Plugin context (provides `config`, `log`).
+* @param ctx - Plugin context (provides `state`, `config`, `log`).
 * @returns The written file path, or `null` when disabled.
 * @example
 * ```ts
@@ -4072,7 +4463,7 @@ async function generateNotFound(ctx) {
 		ctx.log.debug("build:not-found", { skipped: true });
 		return null;
 	}
-	const html = await resolveHtml(notFound);
+	const html = substituteAssetPlaceholders(ctx, await resolveHtml(notFound));
 	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
 	const file = node_path$1.default.join(outDir, "404.html");
 	await (0, node_fs_promises.writeFile)(file, html, "utf8");
@@ -4650,7 +5041,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);
 		},
 		/**
@@ -4811,45 +5202,9 @@ const dataPlugin = createPlugin$1("data", {
 const HEAD_PLACEHOLDER = "<!--moku:head-->";
 /** Template placeholder for the SSR-rendered body HTML. */
 const BODY_PLACEHOLDER = "<!--moku:body-->";
-/** Template placeholder for the injected asset `<link>`/`<script>` tags. */
-const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
 /** Template placeholder for the page's locale (`<html lang>`). */
 const LANG_PLACEHOLDER = "<!--moku:lang-->";
 /**
-* Read the bundle phase's hashed asset manifest for one kind from `state.buildCache`
-* as a typed {@link BuildCacheEntry} (no `Map<string, unknown>` reads).
-*
-* @param ctx - Plugin context (provides `state`).
-* @param kind - The asset kind key (`"css"` / `"js"`).
-* @returns The hashed-path manifest entry, or an empty object when absent.
-* @example
-* ```ts
-* readManifest(ctx, "css");
-* ```
-*/
-function readManifest(ctx, kind) {
-	const entry = ctx.state.buildCache.get(kind);
-	return entry && typeof entry === "object" ? entry : {};
-}
-/**
-* Build the asset `<link>`/`<script>` tag block from the hashed manifests. Returns
-* an empty string when `config.injectAssets === false`. Asset paths are emitted as
-* absolute (`/`-rooted) URLs.
-*
-* @param ctx - Plugin context (provides `state`, `config`).
-* @returns The injected asset tags, or `""` when injection is disabled.
-* @example
-* ```ts
-* buildAssetTags(ctx);
-* ```
-*/
-function buildAssetTags(ctx) {
-	if (ctx.config.injectAssets === false) return "";
-	const css = Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`);
-	const js = Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`);
-	return [...css, ...js].join("");
-}
-/**
 * Compose the full static HTML document with the in-code shell, injecting the
 * build-id meta tag into `<head>` AFTER the head plugin's composed HTML (build
 * metadata, not content) and the asset tags at the end of `<head>`.
@@ -4868,18 +5223,21 @@ function renderDocument(parts) {
 * Fill a shell template's `<!--moku:lang-->` / `<!--moku:head-->` /
 * `<!--moku:body-->` / `<!--moku:assets-->` placeholders deterministically at build
 * time. `<!--moku:lang-->` carries the page locale (for `<html lang>`), so a single
-* shared template stays locale-correct across every locale.
+* shared template stays locale-correct across every locale. The split
+* `<!--moku:assets:css-->` / `<!--moku:assets:js-->` placeholders inject one asset
+* kind each — for shells that, e.g., link stylesheets in `<head>` but place
+* scripts at the end of `<body>`.
 *
 * @param template - The raw shell template HTML.
 * @param parts - The composed head/body/assets/locale pieces.
 * @returns The filled document string.
 * @example
 * ```ts
-* fillTemplate(shell, { head, body, assets, locale: "en" });
+* fillTemplate(shell, { head, body, assets, assetsCss, assetsJs, locale: "en" });
 * ```
 */
 function fillTemplate(template, parts) {
-	return template.replaceAll(LANG_PLACEHOLDER, parts.locale).replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets);
+	return template.replaceAll(LANG_PLACEHOLDER, parts.locale).replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets).replaceAll(CSS_ASSETS_PLACEHOLDER, parts.assetsCss).replaceAll(JS_ASSETS_PLACEHOLDER, parts.assetsJs);
 }
 /**
 * Resolve the compiled entry for a manifest definition, asserting the router
@@ -4928,29 +5286,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;
 }
@@ -5215,6 +5588,8 @@ async function renderInstance(ctx, instance, shell, reuse) {
 		head: composeHeadHtml(ctx, instance, url, routeContext, data),
 		body: renderBodyCached(ctx, instance, routeContext, data, reuse),
 		assets: shell.assets,
+		assetsCss: shell.assetsCss,
+		assetsJs: shell.assetsJs,
 		locale
 	};
 	const html = shell.template === null ? renderDocument(parts) : fillTemplate(shell.template, parts);
@@ -5254,26 +5629,30 @@ 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),
+		assetsCss: buildAssetTags(ctx, "css"),
+		assetsJs: buildAssetTags(ctx, "js"),
 		template,
 		defaultLocale: ctx.require(i18nPlugin).defaultLocale()
 	};
 }
 /**
 * 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 +5768,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 {
@@ -5397,37 +5776,6 @@ async function renderPages(ctx, options) {
 		rootHtml: findRootHtml(rendered)
 	};
 }
-/**
-* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
-* preserving the nested directory structure. Skips silently (returns `null`) when
-* the source directory does not exist.
-*
-* @param ctx - Plugin context (provides `config`, `log`).
-* @returns The copy result, or `null` when the public directory is absent.
-* @example
-* ```ts
-* const result = await copyPublic(ctx);
-* ```
-*/
-async function copyPublic(ctx) {
-	const from = ctx.config.publicDir ?? "public";
-	if (!(0, node_fs.existsSync)(from)) {
-		ctx.log.debug("build:public", {
-			skipped: true,
-			from
-		});
-		return null;
-	}
-	await (0, node_fs_promises.cp)(from, ctx.config.outDir, { recursive: true });
-	ctx.log.debug("build:public", {
-		from,
-		dest: ctx.config.outDir
-	});
-	return {
-		from: node_path$1.default.normalize(from),
-		copied: 1
-	};
-}
 //#endregion
 //#region src/plugins/build/phases/sitemap.ts
 /**
@@ -5464,7 +5812,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 +5837,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 +5943,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 +5961,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 +5998,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
@@ -5651,6 +6057,7 @@ const PHASE_ORDER = [
 	"public",
 	"not-found",
 	"locale-redirects",
+	"cache-headers",
 	"root-index"
 ];
 /**
@@ -5681,17 +6088,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`
@@ -5739,7 +6152,7 @@ async function runOutputs(ctx) {
 }
 /**
 * Executes the full SSG pipeline for one run: clean → bundle → content/images →
-* pages → feeds/sitemap/og-images → root-index. Orchestrates `ctx.require` pulls
+* pages → feeds/sitemap/og-images → cache-headers → root-index. Orchestrates `ctx.require` pulls
 * and `Promise.all` only — never inlines dependency domain logic. Emits a
 * `build:phase` boundary per phase and `build:complete` once at the end.
 *
@@ -5753,7 +6166,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 +6177,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, {
@@ -5777,6 +6193,7 @@ async function runPipeline(ctx, options) {
 	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext, { reuse: plan.renderReuse }));
 	await withPhase(phaseContext, "content-images", () => copyContentImages(phaseContext));
 	await runOutputs(phaseContext);
+	if (phaseContext.config.cacheHeaders !== false) await withPhase(phaseContext, "cache-headers", () => generateCacheHeaders(phaseContext));
 	await withPhase(phaseContext, "root-index", async () => {
 		if (pages.rootHtml !== null) await (0, node_fs_promises.writeFile)(node_path$1.default.join(outDir, "index.html"), pages.rootHtml, "utf8");
 	});
@@ -10063,6 +10480,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 +10525,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 +10584,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 +10640,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 +10664,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 +10684,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 +10707,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 +10719,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 +10733,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);
 			}
 		});
 	};
@@ -10455,6 +10921,11 @@ function createSpaKernel(state, config, emit, deps) {
 	};
 	/**
 	* 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.
@@ -10465,10 +10936,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 });
@@ -10548,13 +11023,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);
 		/**
@@ -10586,15 +11064,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();
@@ -10610,14 +11089,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 {
 		/**
@@ -11218,9 +11700,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
@@ -11251,8 +11736,7 @@ function buildSanitizeSchema() {
 			"*": [
 				...baseAttributes["*"] ?? [],
 				"className",
-				"class",
-				"style"
+				"class"
 			],
 			aside: [
 				...baseAttributes.aside ?? [],