@moku-labs/web 2.4.14 → 2.4.16

package/dist/index.mjs

@@ -4622,9 +4622,8 @@ function dataApi(ctx) {
 	return {
 		/**
 		* READ (browser) — fetch (and cache) the persisted data for a page path.
-		* Concurrent calls for one path share one in-flight request. While a preload
-		* bundle is in flight, it waits for the bundle and fetches the single file
-		* only if the bundle did not bring the path.
+		* Concurrent calls for one path share one in-flight request. It never waits
+		* for an in-flight preload bundle: an uncached path is fetched at once.
 		* Returns the raw JSON as `unknown`, which the route uses directly as `ctx.data`
 		* (no route `.parse()`); returns `null` if the fetch or JSON parse fails (so
 		* `spa` can fall back to HTML).
@@ -4638,10 +4637,6 @@ function dataApi(ctx) {
 		*/
 		async at(path) {
 			if (ctx.state.cache.has(path)) return ctx.state.cache.get(path);
-			if (ctx.state.bundle) {
-				await ctx.state.bundle;
-				if (ctx.state.cache.has(path)) return ctx.state.cache.get(path);
-			}
 			const inFlight = ctx.state.pending.get(path);
 			if (inFlight) return inFlight;
 			const request = fetchAndCache(ctx, path);
@@ -4716,7 +4711,7 @@ const defaultDataConfig = {
 //#region src/plugins/data/preload.ts
 /**
 * Fetches the bundle and caches every path not already cached. Never rejects:
-* a failed fetch leaves lazy `at()` working. Clears the preload slots when done.
+* a failed fetch leaves lazy `at()` working. Clears `cancelPreload` when done.
 *
 * @param ctx - The data plugin context.
 * @param signal - Aborts the fetch on stop.
@@ -4732,7 +4727,7 @@ async function fill(ctx, signal) {
 		const bundle = response.ok ? await response.json() : {};
 		for (const [path, data] of Object.entries(bundle)) if (!signal.aborted && !ctx.state.cache.has(path)) ctx.state.cache.set(path, data);
 	} catch {} finally {
-		ctx.state.bundle = ctx.state.cancelPreload = null;
+		ctx.state.cancelPreload = null;
 	}
 }
 /**
@@ -4750,7 +4745,7 @@ function startPreload(ctx) {
 	if (ctx.config.preload !== "all" || typeof document === "undefined" || ctx.state.cancelPreload !== null || nav?.connection?.saveData === true) return;
 	const controller = new AbortController();
 	const run = () => {
-		ctx.state.bundle = fill(ctx, controller.signal);
+		fill(ctx, controller.signal);
 	};
 	const idle = typeof requestIdleCallback === "function";
 	const handle = idle ? requestIdleCallback(run, { timeout: 2e3 }) : setTimeout(run, 0);
@@ -4779,7 +4774,7 @@ function stopPreload(ctx) {
 * Creates initial data state: a null `lastWrite` slot (populated by the Node
 * `write()` side), an empty `cache` (populated lazily by the browser `at(path)`
 * side on first fetch), an empty `pending` map of in-flight fetches, and no
-* preload bundle in flight or scheduled.
+* preload scheduled.
 *
 * @param _ctx - Minimal context with global and config.
 * @param _ctx.global - Global framework configuration.
@@ -4795,7 +4790,6 @@ function createDataState(_ctx) {
 		lastWrite: null,
 		cache: /* @__PURE__ */ new Map(),
 		pending: /* @__PURE__ */ new Map(),
-		bundle: null,
 		cancelPreload: null
 	};
 }
@@ -10517,89 +10511,6 @@ function notifyNavEnd(state, route = EMPTY_ROUTE) {
 	}
 }
 //#endregion
-//#region src/plugins/spa/progress.ts
-/** Delay before the bar appears, so fast navigations show no indicator. */
-const START_DELAY_MS = 150;
-/** Interval between trickle increments while loading. */
-const TRICKLE_MS = 300;
-/** Linger before the completed bar is reset/hidden. */
-const DONE_LINGER_MS = 200;
-/** Ceiling the bar trickles to while still loading (never reaches 100% until done). */
-const TRICKLE_CEIL = 90;
-/** No-op progress bar used when disabled or in a headless context. */
-const NOOP_BAR = {
-	start() {},
-	done() {}
-};
-/**
-* Creates the in-house progress bar (150ms delay + trickle). A no-op shell when
-* progress is disabled or no DOM is present. The progress element is created
-* once (prepended to `<body>` as `<div data-progress>`) and reused across navs.
-*
-* @param enabled - Whether the progress bar is active.
-* @returns A {@link ProgressBar} with `start`/`done`. Disabled/headless → no-ops.
-* @example
-* const bar = createProgressBar(true);
-* bar.start();
-* bar.done();
-*/
-function createProgressBar(enabled) {
-	if (!enabled || typeof document === "undefined") return NOOP_BAR;
-	const element = document.createElement("div");
-	element.dataset.progress = "";
-	document.body.prepend(element);
-	let delayTimer;
-	let trickleTimer;
-	let width = 0;
-	/**
-	* Step the trickle upward toward the ceiling and reschedule.
-	*
-	* @example
-	* trickle();
-	*/
-	const trickle = () => {
-		if (width >= TRICKLE_CEIL) return;
-		width = Math.min(TRICKLE_CEIL, width + 5 + Math.random() * 10);
-		element.style.width = `${String(width)}%`;
-		trickleTimer = setTimeout(trickle, TRICKLE_MS);
-	};
-	/**
-	* Show the bar after the start delay and begin trickling.
-	*
-	* @example
-	* start();
-	*/
-	const start = () => {
-		delayTimer = setTimeout(() => {
-			width = 15;
-			element.style.width = "15%";
-			element.dataset.active = "";
-			trickle();
-		}, START_DELAY_MS);
-	};
-	/**
-	* Complete the bar to 100%, then reset/hide it after a short linger.
-	*
-	* @example
-	* done();
-	*/
-	const done = () => {
-		clearTimeout(delayTimer);
-		clearTimeout(trickleTimer);
-		element.style.width = "100%";
-		element.dataset.active = "";
-		setTimeout(() => {
-			delete element.dataset.active;
-			element.style.width = "0%";
-			width = 0;
-		}, DONE_LINGER_MS);
-	};
-	return {
-		start,
-		done
-	};
-}
-//#endregion
 //#region src/plugins/spa/router.ts
 /**
 * Read the Navigation API global, or `undefined` when unsupported.
@@ -10627,9 +10538,10 @@ function isInternalLink(url) {
 /**
 * 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.
+* same-page checks, history entries, fetches, scroll keys and the preload cache key
+* 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. The hash is not part of it.
 *
 * @param target - The URL or Location to read.
 * @param target.pathname - The path component.
@@ -10667,26 +10579,42 @@ function restoreScrollPosition(path) {
 	} catch {}
 }
 /**
-* Fetch a page and hand its HTML to the handlers; on any error fall back to a
+* Fetch a page's HTML. The one fetch-and-check shared by navigation and preload
+* (`prefetch.ts`): a response that is not ok is an error, never HTML to swap in.
+*
+* @param pathname - The page path (pathname + search).
+* @param signal - Aborts the request.
+* @returns The page HTML.
+* @throws {Error} When the response is not ok (`HTTP <status>`), or the fetch fails or aborts.
+* @example
+* await fetchPage("/about"); // "<!doctype html>…" — rejects with "HTTP 404" on a missing page
+*/
+async function fetchPage(pathname, signal) {
+	const response = await (signal ? fetch(pathname, { signal }) : fetch(pathname));
+	if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
+	return response.text();
+}
+/**
+* Load 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.
+* When `signal` aborts (this navigation was superseded by a newer one) 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`).
+* @param load - Where the HTML comes from: {@link fetchPage} by default; the kernel
+*   passes a loader that serves a preloaded page first (`loadWithPrefetch`).
 * @returns A promise that resolves once the swap (or fallback) is dispatched.
 * @example
 * await performNavigation("/about", handlers, navEvent.signal);
 */
-async function performNavigation(pathname, handlers, signal) {
+async function performNavigation(pathname, handlers, signal, load = fetchPage) {
 	handlers.onStart(pathname);
 	try {
-		const response = await (signal ? fetch(pathname, { signal }) : fetch(pathname));
-		if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
-		const html = await response.text();
+		const html = await load(pathname, signal);
 		if (signal?.aborted) return;
 		handlers.onEnd(html, pathname);
 	} catch {
@@ -10794,18 +10722,16 @@ function swapRegion(doc, swapSelector, transition, onSwapped, beforeCapture) {
 	return true;
 }
 /**
-* Resolve a navigable internal URL from a click event, or `undefined` when the
-* click should not be intercepted (modifier keys, non-anchor, external, new-tab).
+* Resolve the internal URL a link leads to, or `undefined` when the SPA leaves it
+* to the browser (no anchor, `target="_blank"`, another origin, a static asset). The
+* one link rule shared by the click interceptor and the preloader (`prefetch.ts`).
 *
-* @param event - The click event to inspect.
-* @returns The internal URL to navigate to, or `undefined`.
+* @param anchor - The link element, or nothing.
+* @returns The internal URL, or `undefined`.
 * @example
-* const url = resolveClickTarget(event);
+* resolveLinkTarget(document.querySelector("a[href='/about']"))?.pathname; // "/about"
 */
-function resolveClickTarget(event) {
-	if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return void 0;
-	if (event.defaultPrevented) return void 0;
-	const anchor = event.target?.closest("a");
+function resolveLinkTarget(anchor) {
 	if (!anchor || anchor.target === "_blank") return void 0;
 	let url;
 	try {
@@ -10816,6 +10742,20 @@ function resolveClickTarget(event) {
 	return isInternalLink(url) ? url : void 0;
 }
 /**
+* Resolve a navigable internal URL from a click event, or `undefined` when the
+* click should not be intercepted (modifier keys, non-anchor, external, new-tab).
+*
+* @param event - The click event to inspect.
+* @returns The internal URL to navigate to, or `undefined`.
+* @example
+* const url = resolveClickTarget(event);
+*/
+function resolveClickTarget(event) {
+	if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return void 0;
+	if (event.defaultPrevented) return void 0;
+	return resolveLinkTarget(event.target?.closest("a"));
+}
+/**
 * Attach the History-API click/popstate interception path (used when the
 * Navigation API is unavailable).
 *
@@ -10948,11 +10888,412 @@ function attachRouter(handlers, navigate, isOwnPush) {
 	return navigation ? attachNavigationApi(navigation, handlers, navigate, isOwnPush) : attachHistoryFallback(handlers, navigate);
 }
 //#endregion
+//#region src/plugins/spa/prefetch.ts
+/**
+* @file spa plugin — opt-in in-memory HTML preload cache (`spa.prefetch`).
+* @see README.md
+*/
+const HOVER_DELAY_MS = 65;
+const TTL_MS = 3e4;
+const MAX_ENTRIES = 20;
+const VISIBLE_CONCURRENCY = 2;
+const IDLE_FALLBACK_MS = 200;
+const SLOW_CONNECTION = /(^|-)2g$/;
+const PRESS = {
+	capture: true,
+	passive: true
+};
+const HOVER = { passive: true };
+/**
+* Read `navigator.connection` (mirrors `getNavigation()` in `router.ts`).
+*
+* @returns The connection info, or `undefined` where the browser has none.
+* @example
+* getConnection()?.saveData; // true with data saving on
+*/
+function getConnection() {
+	return navigator.connection;
+}
+/**
+* Whether no preload may start now: data saving on, or a 2G connection.
+*
+* @returns True when preloads must wait.
+* @example
+* isConstrained(); // true on effectiveType "slow-2g"
+*/
+function isConstrained() {
+	const connection = getConnection();
+	return connection?.saveData === true || SLOW_CONNECTION.test(connection?.effectiveType ?? "");
+}
+/**
+* The link an event happened on.
+*
+* @param event - A press or mouse event.
+* @returns The closest `<a>`, or nothing.
+* @example
+* anchorOf(event); // <a href="/about"> for a tap on the <span> inside it
+*/
+function anchorOf(event) {
+	return event.target instanceof Element ? event.target.closest("a") : void 0;
+}
+/**
+* Run `task` in idle time, or after 200 ms where `requestIdleCallback` is missing.
+*
+* @param task - The work to run.
+* @returns Cancels the task.
+* @example
+* const cancel = whenIdle(drain); // cancel() before idle time: drain never runs
+*/
+function whenIdle(task) {
+	if (typeof requestIdleCallback === "function") {
+		const handle = requestIdleCallback(task);
+		return () => cancelIdleCallback(handle);
+	}
+	const handle = setTimeout(task, IDLE_FALLBACK_MS);
+	return () => clearTimeout(handle);
+}
+/**
+* Build the preloader: press and hover listeners on `document` at once, and for
+* `"visible"` one IntersectionObserver that {@link Prefetcher.observe} feeds.
+*
+* @param options - The mode, the HTML-path check and the clock.
+* @returns The live preloader.
+* @example
+* createPrefetcher({ mode: "intent", usesHtml: () => true }).take("/about"); // undefined
+*/
+function createPrefetcher(options) {
+	const now = options.now ?? Date.now;
+	const cache = /* @__PURE__ */ new Map();
+	const hoverTimers = /* @__PURE__ */ new Map();
+	const queue = [];
+	let visibleInFlight = 0;
+	let cancelDrain;
+	/**
+	* Whether an entry is older than the TTL.
+	*
+	* @param entry - A cache entry.
+	* @returns True when the entry must not be used.
+	* @example
+	* isExpired(entry); // true 30_001 ms after it started
+	*/
+	const isExpired = (entry) => now() - entry.startedAt > TTL_MS;
+	/**
+	* Abort an entry's request and remove it.
+	*
+	* @param key - The entry's path.
+	* @param entry - The entry.
+	* @example
+	* drop("/a/", entry);
+	*/
+	const drop = (key, entry) => {
+		entry.controller.abort();
+		cache.delete(key);
+	};
+	/**
+	* The path a link would preload, or `undefined` when it is not eligible.
+	*
+	* @param anchor - The link, or nothing.
+	* @returns The path (pathname + search), or `undefined`.
+	* @example
+	* pathOf(document.querySelector("a[href='/about?x=1#top']")); // "/about?x=1"
+	*/
+	const pathOf = (anchor) => {
+		const url = resolveLinkTarget(anchor);
+		if (!url || anchor?.hasAttribute("download")) return void 0;
+		const path = pathWithSearch(url);
+		return path !== pathWithSearch(location) && options.usesHtml(path) ? path : void 0;
+	};
+	/**
+	* Start one preload, unless the connection forbids it or the path is already cached.
+	*
+	* @param path - The page path.
+	* @returns The new entry, or `undefined` when nothing started.
+	* @example
+	* start("/about"); // { promise, startedAt, controller }
+	*/
+	const start = (path) => {
+		if (isConstrained()) return void 0;
+		for (const [key, entry] of cache) if (isExpired(entry)) drop(key, entry);
+		if (cache.has(path)) return void 0;
+		for (const [key, entry] of cache) {
+			if (cache.size < MAX_ENTRIES) break;
+			drop(key, entry);
+		}
+		const controller = new AbortController();
+		const promise = fetchPage(path, controller.signal);
+		const entry = {
+			promise,
+			startedAt: now(),
+			controller
+		};
+		cache.set(path, entry);
+		promise.catch(() => {
+			if (cache.get(path) === entry) cache.delete(path);
+		});
+		return entry;
+	};
+	/**
+	* Preload a link when it is eligible.
+	*
+	* @param anchor - The link, or nothing.
+	* @example
+	* preloadLink(document.querySelector("a"));
+	*/
+	const preloadLink = (anchor) => {
+		const path = pathOf(anchor);
+		if (path !== void 0) start(path);
+	};
+	/**
+	* Start queued `"visible"` preloads while fewer than 2 are in flight.
+	*
+	* @example
+	* cancelDrain = whenIdle(drain);
+	*/
+	const drain = () => {
+		cancelDrain = void 0;
+		while (visibleInFlight < VISIBLE_CONCURRENCY) {
+			const path = queue.shift();
+			if (path === void 0) return;
+			const entry = start(path);
+			if (!entry) continue;
+			visibleInFlight += 1;
+			entry.promise.catch(() => "").then(() => {
+				visibleInFlight -= 1;
+				scheduleDrain();
+			});
+		}
+	};
+	/**
+	* Drain the queue in idle time, once.
+	*
+	* @example
+	* scheduleDrain();
+	*/
+	const scheduleDrain = () => {
+		if (cancelDrain === void 0 && queue.length > 0) cancelDrain = whenIdle(drain);
+	};
+	/**
+	* `pointerdown` / `touchstart`: preload at once.
+	*
+	* @param event - The press.
+	* @example
+	* document.addEventListener("pointerdown", onPress, PRESS);
+	*/
+	const onPress = (event) => {
+		preloadLink(anchorOf(event));
+	};
+	/**
+	* `mouseover`: preload after 65 ms on the link.
+	*
+	* @param event - The mouse event.
+	* @example
+	* document.addEventListener("mouseover", onOver, HOVER);
+	*/
+	const onOver = (event) => {
+		const anchor = anchorOf(event);
+		if (!anchor || hoverTimers.has(anchor)) return;
+		const timer = setTimeout(() => {
+			hoverTimers.delete(anchor);
+			preloadLink(anchor);
+		}, HOVER_DELAY_MS);
+		hoverTimers.set(anchor, timer);
+	};
+	/**
+	* `mouseout`: cancel the hover timer, unless the mouse only moved inside the same link.
+	*
+	* @param event - The mouse event.
+	* @example
+	* document.addEventListener("mouseout", onOut, HOVER);
+	*/
+	const onOut = (event) => {
+		const anchor = anchorOf(event);
+		const into = event.relatedTarget;
+		if (!anchor || into instanceof Node && anchor.contains(into)) return;
+		clearTimeout(hoverTimers.get(anchor));
+		hoverTimers.delete(anchor);
+	};
+	const observer = options.mode === "visible" && typeof IntersectionObserver === "function" ? new IntersectionObserver((entries, self) => {
+		for (const entry of entries) {
+			if (!entry.isIntersecting) continue;
+			self.unobserve(entry.target);
+			const path = pathOf(entry.target.closest("a"));
+			if (path !== void 0) queue.push(path);
+		}
+		scheduleDrain();
+	}) : void 0;
+	document.addEventListener("pointerdown", onPress, PRESS);
+	document.addEventListener("touchstart", onPress, PRESS);
+	document.addEventListener("mouseover", onOver, HOVER);
+	document.addEventListener("mouseout", onOut, HOVER);
+	return {
+		/**
+		* Take the preload for `path` and remove it (see {@link Prefetcher.take}).
+		*
+		* @param path - The page path.
+		* @returns The page HTML promise, or `undefined`.
+		* @example
+		* prefetcher.take("/about");
+		*/
+		take(path) {
+			const entry = cache.get(path);
+			if (!entry) return void 0;
+			if (isExpired(entry)) {
+				drop(path, entry);
+				return;
+			}
+			cache.delete(path);
+			return entry.promise;
+		},
+		/**
+		* Watch every eligible link in the document (see {@link Prefetcher.observe}).
+		*
+		* @example
+		* prefetcher.observe();
+		*/
+		observe() {
+			if (!observer) return;
+			observer.disconnect();
+			queue.length = 0;
+			for (const anchor of document.querySelectorAll("a[href]")) if (pathOf(anchor) !== void 0) observer.observe(anchor);
+		},
+		/**
+		* Release everything (see {@link Prefetcher.dispose}).
+		*
+		* @example
+		* prefetcher.dispose();
+		*/
+		dispose() {
+			document.removeEventListener("pointerdown", onPress, PRESS);
+			document.removeEventListener("touchstart", onPress, PRESS);
+			document.removeEventListener("mouseover", onOver, HOVER);
+			document.removeEventListener("mouseout", onOut, HOVER);
+			observer?.disconnect();
+			for (const timer of hoverTimers.values()) clearTimeout(timer);
+			hoverTimers.clear();
+			cancelDrain?.();
+			cancelDrain = void 0;
+			queue.length = 0;
+			for (const [key, entry] of cache) drop(key, entry);
+		}
+	};
+}
+/**
+* The HTML loader the kernel hands to `performNavigation`: a preloaded page when there is
+* one, else a normal fetch. A failed preload falls through to one real fetch, so it never
+* leads to a full reload; only a failed real fetch does, as without preloading.
+*
+* @param prefetcher - The live preloader, or `null` (mode `false`, or stopped).
+* @param path - The page path (pathname + search).
+* @param signal - The navigation's abort signal; never passed to the preload.
+* @returns The page HTML.
+* @throws {Error} When the real fetch fails, or the navigation was aborted after its preload failed.
+* @example
+* await loadWithPrefetch(state.prefetch, "/about", signal); // the preloaded HTML, no new request
+*/
+async function loadWithPrefetch(prefetcher, path, signal) {
+	const hit = prefetcher?.take(path);
+	if (hit) try {
+		return await hit;
+	} catch {
+		signal?.throwIfAborted();
+	}
+	return fetchPage(path, signal);
+}
+//#endregion
+//#region src/plugins/spa/progress.ts
+/** Delay before the bar appears, so fast navigations show no indicator. */
+const START_DELAY_MS = 150;
+/** Interval between trickle increments while loading. */
+const TRICKLE_MS = 300;
+/** Linger before the completed bar is reset/hidden. */
+const DONE_LINGER_MS = 200;
+/** Ceiling the bar trickles to while still loading (never reaches 100% until done). */
+const TRICKLE_CEIL = 90;
+/** No-op progress bar used when disabled or in a headless context. */
+const NOOP_BAR = {
+	start() {},
+	done() {}
+};
+/**
+* Creates the in-house progress bar (150ms delay + trickle). A no-op shell when
+* progress is disabled or no DOM is present. The progress element is created
+* once (prepended to `<body>` as `<div data-progress>`) and reused across navs.
+*
+* @param enabled - Whether the progress bar is active.
+* @returns A {@link ProgressBar} with `start`/`done`. Disabled/headless → no-ops.
+* @example
+* const bar = createProgressBar(true);
+* bar.start();
+* bar.done();
+*/
+function createProgressBar(enabled) {
+	if (!enabled || typeof document === "undefined") return NOOP_BAR;
+	const element = document.createElement("div");
+	element.dataset.progress = "";
+	document.body.prepend(element);
+	let delayTimer;
+	let trickleTimer;
+	let width = 0;
+	/**
+	* Step the trickle upward toward the ceiling and reschedule.
+	*
+	* @example
+	* trickle();
+	*/
+	const trickle = () => {
+		if (width >= TRICKLE_CEIL) return;
+		width = Math.min(TRICKLE_CEIL, width + 5 + Math.random() * 10);
+		element.style.width = `${String(width)}%`;
+		trickleTimer = setTimeout(trickle, TRICKLE_MS);
+	};
+	/**
+	* Show the bar after the start delay and begin trickling.
+	*
+	* @example
+	* start();
+	*/
+	const start = () => {
+		delayTimer = setTimeout(() => {
+			width = 15;
+			element.style.width = "15%";
+			element.dataset.active = "";
+			trickle();
+		}, START_DELAY_MS);
+	};
+	/**
+	* Complete the bar to 100%, then reset/hide it after a short linger.
+	*
+	* @example
+	* done();
+	*/
+	const done = () => {
+		clearTimeout(delayTimer);
+		clearTimeout(trickleTimer);
+		element.style.width = "100%";
+		element.dataset.active = "";
+		setTimeout(() => {
+			delete element.dataset.active;
+			element.style.width = "0%";
+			width = 0;
+		}, DONE_LINGER_MS);
+	};
+	return {
+		start,
+		done
+	};
+}
+//#endregion
 //#region src/plugins/spa/state.ts
 /** Error prefix for spa config-validation failures (spec/11 Part-3). */
 const ERROR_PREFIX$1 = "[web]";
 /** Last-resort `swapSelector` when neither config nor defaults supply one. */
 const FALLBACK_SWAP_SELECTOR = "main > section";
+/** Every value `spa.prefetch` accepts. */
+const PREFETCH_MODES = new Set([
+	false,
+	"intent",
+	"visible"
+]);
 /**
 * Resolve the `viewTransitions` config value into the default {@link TransitionMode}:
 * `true` → `"crossfade"`, `false` → `"none"`, a named mode → itself.
@@ -10967,13 +11308,28 @@ function resolveDefaultTransition(raw) {
 	if (raw === false) return "none";
 	return raw;
 }
+/**
+* Validate `spa.prefetch` (spec/11 Part-3 error). An untyped config can carry any value,
+* so a typo like `"hover"` fails at init instead of silently disabling the preload.
+*
+* @param mode - The raw `prefetch` config value (absent ⇒ `false`).
+* @returns The validated mode.
+* @throws {Error} When the value is not `false`, `"intent"` or `"visible"`.
+* @example
+* resolvePrefetchMode(undefined); // false
+*/
+function resolvePrefetchMode(mode = false) {
+	if (!PREFETCH_MODES.has(mode)) throw new Error(`${ERROR_PREFIX$1} spa.prefetch must be false, "intent" or "visible". Got ${JSON.stringify(mode)}.\n  Set spa.prefetch to one of the allowed values, or leave it out.`);
+	return mode;
+}
 /** Default SPA config (declared as a value — no inline assertion). */
 const defaultSpaConfig = {
 	swapSelector: "main > section",
 	viewTransitions: false,
 	scrollRestoration: "top",
 	progressBar: true,
-	islands: []
+	islands: [],
+	prefetch: false
 };
 /**
 * Whether a selector is syntactically valid (parseable by the DOM). Falls back
@@ -11000,7 +11356,8 @@ function isValidSelector(selector) {
 *
 * @param config - The raw spa config to validate.
 * @returns The fully-resolved config with defaults applied.
-* @throws {Error} When `swapSelector` is empty or not a valid CSS selector.
+* @throws {Error} When `swapSelector` is empty or not a valid CSS selector, or `prefetch`
+*   is not one of its three values.
 * @example
 * const resolved = resolveSpaConfig({ swapSelector: "main > section" });
 */
@@ -11015,7 +11372,8 @@ function resolveSpaConfig(config) {
 		defaultTransition,
 		scrollRestoration: config.scrollRestoration ?? "top",
 		progressBar: config.progressBar ?? true,
-		islands: config.islands ?? []
+		islands: config.islands ?? [],
+		prefetch: resolvePrefetchMode(config.prefetch)
 	};
 }
 /**
@@ -11039,7 +11397,8 @@ function createState(_ctx) {
 		destroyRouter: null,
 		started: false,
 		navigate: null,
-		kernel: null
+		kernel: null,
+		prefetch: null
 	};
 }
 //#endregion
@@ -11077,6 +11436,21 @@ function currentLocationUrl() {
 	return location.pathname + location.search;
 }
 /**
+* Whether a navigation to `path` renders from fetched HTML, so a preload of it is used.
+*
+* @param deps - The router and the optional data reader.
+* @param path - The page path (pathname + search).
+* @returns False when the client DATA path renders the page.
+* @example
+* usesHtml({ router, head }, "/en/about/"); // true: no data reader, every page is HTML
+*/
+function usesHtml(deps, path) {
+	if (deps.router.mode() === "ssg") return true;
+	const route = deps.router.match(path.split("?")[0] ?? path)?.route;
+	if (!route?._handlers.render) return true;
+	return !isClientOnlyRoute(deps.router.mode(), route) && !deps.dataAt;
+}
+/**
 * Apply the matched route's `head` config to the live document (minimal client
 * head-sync for the DATA path: title only — the full meta sync runs on the
 * HTML-over-fetch path from the fetched `<head>`). The title is resolved through
@@ -11236,6 +11610,7 @@ function createSpaKernel(state, config, emit, deps) {
 			const routeSlice = islandRouteContext(pathname);
 			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 			notifyNavEnd(state, routeSlice);
+			state.prefetch?.observe();
 		}, applyPendingScroll)) {
 			handleError();
 			location.href = pathname;
@@ -11350,6 +11725,7 @@ function createSpaKernel(state, config, emit, deps) {
 			renderVNode(vnode, region);
 			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 			notifyNavEnd(state, routeSlice);
+			state.prefetch?.observe();
 		};
 		runSwap(renderAndMount, pendingTransition, applyPendingScroll);
 		state.currentUrl = pathname;
@@ -11398,12 +11774,14 @@ function createSpaKernel(state, config, emit, deps) {
 		const resolvedRender = await resolveDataRender(pathname);
 		if (resolvedRender === false) {
 			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
+			state.prefetch?.observe();
 			return;
 		}
 		const { vnode, region } = resolvedRender;
 		const { renderVNode } = await import("./render-CkdqOmsm.mjs");
 		renderVNode(vnode, region);
 		scanAndMount(state, emit, resolved.swapSelector, routeSlice);
+		state.prefetch?.observe();
 	};
 	/**
 	* Unified navigation: try the client DATA path first (only when the `data`
@@ -11427,7 +11805,7 @@ function createSpaKernel(state, config, emit, deps) {
 		handleStart(pathname);
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname, signal)) return;
 		if (signal?.aborted) return;
-		await performNavigation(pathname, handlers, signal);
+		await performNavigation(pathname, handlers, signal, (path, loadSignal) => loadWithPrefetch(state.prefetch, path, loadSignal));
 	};
 	/**
 	* Programmatic navigation entry (`app.spa.navigate` / `ctx.navigate`). A link click or the
@@ -11495,10 +11873,17 @@ function createSpaKernel(state, config, emit, deps) {
 				supersedeProgrammatic();
 				return navigate(pathname, scrollToTop, signal, scrollOverride);
 			}, () => pushingOwnUrl);
+			if (resolved.prefetch !== false) state.prefetch = createPrefetcher({
+				mode: resolved.prefetch,
+				usesHtml: (path) => usesHtml(deps, path)
+			});
 			const matchPath = state.currentUrl.split("?")[0] ?? state.currentUrl;
 			const hit = deps.router.match(matchPath);
 			if (hit?.route._handlers.render && isClientOnlyRoute(deps.router.mode(), hit.route)) bootRender(state.currentUrl);
-			else scanAndMount(state, emit, resolved.swapSelector, islandRouteContext(state.currentUrl));
+			else {
+				scanAndMount(state, emit, resolved.swapSelector, islandRouteContext(state.currentUrl));
+				state.prefetch?.observe();
+			}
 			state.started = true;
 		},
 		/**
@@ -11538,6 +11923,8 @@ function createSpaKernel(state, config, emit, deps) {
 			if (typeof document === "undefined") return;
 			state.destroyRouter?.();
 			state.destroyRouter = null;
+			state.prefetch?.dispose();
+			state.prefetch = null;
 			location.assign(url);
 		},
 		/**
@@ -11558,6 +11945,8 @@ function createSpaKernel(state, config, emit, deps) {
 		dispose() {
 			state.destroyRouter?.();
 			state.destroyRouter = null;
+			state.prefetch?.dispose();
+			state.prefetch = null;
 			unmountAll(state, emit);
 			progress = void 0;
 			state.started = false;