@moku-labs/web 1.6.2 → 1.7.0

package/README.md

@@ -15,7 +15,7 @@ Built on the [@moku-labs/core](https://github.com/moku-labs/core) micro-kernel
 [![CI](https://github.com/moku-labs/web/actions/workflows/ci.yml/badge.svg)](https://github.com/moku-labs/web/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@moku-labs/web?logo=npm&color=cb3837&label=npm)](https://www.npmjs.com/package/@moku-labs/web)
 [![types](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)](#requirements)
-[![browser bundle](https://img.shields.io/badge/browser%20entry-~45%20kB%20gzip-2da44e)](#the-browser-entry-is-guaranteed-node-free)
+[![browser bundle](https://img.shields.io/badge/browser%20entry-~50%20kB%20gzip-2da44e)](#the-browser-entry-is-guaranteed-node-free)
 [![node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](#requirements)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
@@ -34,18 +34,21 @@ Built on the [@moku-labs/core](https://github.com/moku-labs/core) micro-kernel
 ---
 
 ```sh
-bun add @moku-labs/web
+bun add @moku-labs/web preact preact-render-to-string
 ```
 
 > [!NOTE]
-> **Status: `0.x` — pre-1.0.** The architecture is stable; the public API is settling but not yet frozen. Pin the version — the npm badge above tracks the current release.
+> `preact` (and `preact-render-to-string`, used by the SSG build) are **peer dependencies** — your app compiles its JSX against the same single `preact` instance the framework renders with. Most package managers install peers automatically, but declare them explicitly so *you* own the version: a second nested copy of preact silently breaks hooks and island hydration.
+
+> [!NOTE]
+> **Status: `1.x` — stable.** The architecture and public API are stable and follow [semver](https://semver.org) — breaking changes land only in a new major. The npm badge above tracks the current release.
 
 ## Why @moku-labs/web
 
 - **SSG first, SPA when you want it.** Render [Preact](https://preactjs.com) pages to static HTML for SEO and instant first paint, then progressively enhance with island hydration and client-side navigation — opt in per project with a single switch.
 - **The route is the contract.** One typed `route()` builder owns `load` → `render` → `head`. The build and the client run the *same* `render`, so there's no second code path to keep in sync. [Jump to the example ↓](#the-route-is-the-contract)
 - **SEO complete out of the box.** Title templates, canonical + `hreflang`, Open Graph / Twitter cards, JSON-LD, RSS / Atom / JSON feeds, `sitemap.xml`, and generated OG images.
-- **The `/browser` entry is guaranteed node-free.** A dedicated client entry whose static import graph references *zero* node modules — native code can never leak into your bundle, no matter your bundler or tree-shaking. A CI gate keeps it under budget (~45 kB gzip today). [Why this matters ↓](#the-browser-entry-is-guaranteed-node-free)
+- **The `/browser` entry is guaranteed node-free.** A dedicated client entry whose static import graph references *zero* node modules — native code can never leak into your bundle, no matter your bundler or tree-shaking. A CI gate keeps it under budget (~50 kB gzip today, 60 kB budget). [Why this matters ↓](#the-browser-entry-is-guaranteed-node-free)
 - **Plugins all the way down.** A tiny isomorphic core (`site`, `i18n`, `router`, `head`, `spa`) plus opt-in node-only plugins (`content`, `build`, `deploy`, `cli`), each [independently documented](#plugins) and composed in one `createApp` call.
 - **Types do the heavy lifting.** `ctx.data` is inferred from your `.load()`, path params from the route pattern, plugin APIs from their specs — no codegen, no `as`.
 - **i18n is built in.** Locale-aware routes, default-locale fallback, `hreflang` / `og:locale` maps.
@@ -236,7 +239,7 @@ bun run build              # build with tsdown (dual ESM+CJS + ESM-only browser
 bun run test               # all tests (vitest)
 bun run test:unit          # unit tests only
 bun run test:integration   # integration tests only
-bun run test:coverage      # tests with coverage (90% threshold)
+bun run test:coverage      # tests with coverage (85% threshold)
 bun run lint               # biome check + eslint
 bun run lint:fix           # auto-fix lint issues
 bun run format             # format with biome
@@ -246,7 +249,7 @@ bun run check:bundle       # assert the browser bundle is node-free + under the
 
 ## Requirements
 
-- **Node `>= 24`** — the router uses the global [`URLPattern`](https://developer.mozilla.org/docs/Web/API/URLPattern).
+- **Node `>= 24`** — the engines floor declared in `package.json`. (The route matcher is native `RegExp` — no [`URLPattern`](https://developer.mozilla.org/docs/Web/API/URLPattern) global needed, in Node or in any browser.)
 - **Bun `>= 1.3.14`** — the package manager and test runner. Use `bun` exclusively (never npm/yarn/pnpm).
 - **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
 

package/dist/browser.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
-import { n as relativeDataFile, t as dataSuffix } from "./convention-CepUwWmT.mjs";
+import { n as relativeDataFile, t as dataSuffix } from "./convention-Dp650o3y.mjs";
 import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
@@ -1313,21 +1313,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;
 }
@@ -1582,27 +1603,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);
@@ -1613,24 +1629,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`;
 }
 /**
@@ -2433,8 +2473,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`).
@@ -2450,7 +2493,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;
 }
@@ -3021,7 +3066,7 @@ function dataApi(ctx) {
 		* ```
 		*/
 		async write(entries, options) {
-			const { writeData } = await import("./writer-Dc_lx22j.mjs");
+			const { writeData } = await import("./writer-CaoyORyZ.mjs");
 			return writeData(ctx, entries, options);
 		},
 		/**
@@ -3587,6 +3632,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.
@@ -3615,19 +3677,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;
 	}
@@ -3666,23 +3736,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
@@ -3716,7 +3792,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.
 	*
@@ -3727,17 +3816,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.
@@ -3746,7 +3836,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);
@@ -3765,7 +3859,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.
 	*
@@ -3777,7 +3871,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,
@@ -3791,9 +3885,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);
 			}
 		});
 	};
@@ -3979,6 +4073,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.
@@ -3989,10 +4088,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 });
@@ -4072,13 +4175,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 import("./render-BNe0s7fr.mjs");
+		if (signal?.aborted) return;
 		syncDataHead(route, routeContext);
 		unmountPageSpecific(state, emit);
 		/**
@@ -4110,15 +4216,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();
@@ -4134,14 +4241,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 {
 		/**
@@ -4675,6 +4785,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.
@@ -4686,6 +4805,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);

package/dist/{convention-krwh7Y6Q.cjs → convention-BpDfzX7e.cjs}

@@ -36,10 +36,14 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 * ONE function maps a page path to its data suffix, so the browser fetch URL
 * (`baseUrl + suffix`) and the on-disk file (`outputDir + "/" + suffix`) are
 * derived from the same source and cannot drift. The data file mirrors the page
-* URL exactly, mirroring how `build` writes `…/index.html` per page:
+* URL, mirroring how `build` writes `…/index.html` per page:
 *   `/`            → `index.json`
 *   `/en/hello/`   → `en/hello/index.json`
 *   `/en/hello`    → `en/hello/index.json`  (trailing slash normalized)
+*
+* Encoding split: the FETCH suffix ({@link dataSuffix}) keeps the page URL's
+* percent-encoding (the browser requests the encoded path); the FILE path
+* ({@link relativeDataFile}) decodes it, like the page's own `…/index.html`.
 */
 /**
 * Compute the data-file suffix for a page path: strip the leading slash, ensure a
@@ -61,9 +65,29 @@ function dataSuffix(path) {
 	return trimmed.length > 0 ? `${trimmed}/index.json` : "index.json";
 }
 /**
+* Decode a data suffix's percent-escapes so the on-disk file carries the
+* literal name (servers decode the encoded fetch URL before filesystem
+* lookup). Falls back to the raw suffix on malformed escapes.
+*
+* @param suffix - The computed data suffix (possibly percent-encoded).
+* @returns The decoded suffix, or the raw suffix on malformed escapes.
+* @example
+* ```ts
+* decodeSuffix("en/tags/a%20%26%20b/index.json"); // "en/tags/a & b/index.json"
+* ```
+*/
+function decodeSuffix(suffix) {
+	try {
+		return decodeURIComponent(suffix);
+	} catch {
+		return suffix;
+	}
+}
+/**
 * Compute the `outputDir`-relative data file for a page path, joining the trimmed
-* output dir with {@link dataSuffix}. Shared by the Node writer and the pure
-* `fileFor` accessor so the written file and the reported path can never drift.
+* output dir with the DECODED {@link dataSuffix} (servers resolve the decoded
+* request path against literal file names). Shared by the Node writer and the
+* pure `fileFor` accessor so the written file and the reported path never drift.
 *
 * @param outputDir - The configured data output subdir (e.g. `"_data"` or `"_data/"`).
 * @param path - The page URL path (e.g. `/en/hello/`).
@@ -75,7 +99,7 @@ function dataSuffix(path) {
 * ```
 */
 function relativeDataFile(outputDir, path) {
-	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${dataSuffix(path)}`;
+	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${decodeSuffix(dataSuffix(path))}`;
 }
 //#endregion
 Object.defineProperty(exports, "__exportAll", {

package/dist/{convention-CepUwWmT.mjs → convention-Dp650o3y.mjs}

@@ -5,10 +5,14 @@
 * ONE function maps a page path to its data suffix, so the browser fetch URL
 * (`baseUrl + suffix`) and the on-disk file (`outputDir + "/" + suffix`) are
 * derived from the same source and cannot drift. The data file mirrors the page
-* URL exactly, mirroring how `build` writes `…/index.html` per page:
+* URL, mirroring how `build` writes `…/index.html` per page:
 *   `/`            → `index.json`
 *   `/en/hello/`   → `en/hello/index.json`
 *   `/en/hello`    → `en/hello/index.json`  (trailing slash normalized)
+*
+* Encoding split: the FETCH suffix ({@link dataSuffix}) keeps the page URL's
+* percent-encoding (the browser requests the encoded path); the FILE path
+* ({@link relativeDataFile}) decodes it, like the page's own `…/index.html`.
 */
 /**
 * Compute the data-file suffix for a page path: strip the leading slash, ensure a
@@ -30,9 +34,29 @@ function dataSuffix(path) {
 	return trimmed.length > 0 ? `${trimmed}/index.json` : "index.json";
 }
 /**
+* Decode a data suffix's percent-escapes so the on-disk file carries the
+* literal name (servers decode the encoded fetch URL before filesystem
+* lookup). Falls back to the raw suffix on malformed escapes.
+*
+* @param suffix - The computed data suffix (possibly percent-encoded).
+* @returns The decoded suffix, or the raw suffix on malformed escapes.
+* @example
+* ```ts
+* decodeSuffix("en/tags/a%20%26%20b/index.json"); // "en/tags/a & b/index.json"
+* ```
+*/
+function decodeSuffix(suffix) {
+	try {
+		return decodeURIComponent(suffix);
+	} catch {
+		return suffix;
+	}
+}
+/**
 * Compute the `outputDir`-relative data file for a page path, joining the trimmed
-* output dir with {@link dataSuffix}. Shared by the Node writer and the pure
-* `fileFor` accessor so the written file and the reported path can never drift.
+* output dir with the DECODED {@link dataSuffix} (servers resolve the decoded
+* request path against literal file names). Shared by the Node writer and the
+* pure `fileFor` accessor so the written file and the reported path never drift.
 *
 * @param outputDir - The configured data output subdir (e.g. `"_data"` or `"_data/"`).
 * @param path - The page URL path (e.g. `/en/hello/`).
@@ -44,7 +68,7 @@ function dataSuffix(path) {
 * ```
 */
 function relativeDataFile(outputDir, path) {
-	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${dataSuffix(path)}`;
+	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${decodeSuffix(dataSuffix(path))}`;
 }
 //#endregion
 export { relativeDataFile as n, dataSuffix as t };