@lovrozagar/flare 0.1.1 → 0.2.0

package/src/navigation/index.ts

@@ -1,10 +1,11 @@
-import { batch } from "solid-js";
-import type { DeferredTracker } from "../caches/index.ts";
-import { collectDeferredPromises, createDeferredTracker } from "../caches/index.ts";
+import { flush } from "solid-js";
+import type { CachedMatch, DeferredTracker } from "../caches/index.ts";
+import { collectDeferredPromises, createDeferredTracker, resolveCacheTags } from "../caches/index.ts";
+import { applyMatchCacheTags } from "../hydration/index.ts";
 import type { DirectionConfig } from "../direction.ts";
 import { getDirFromLocale } from "../direction.ts";
 import { parseMilliseconds } from "../duration/index.ts";
-import { NotFoundError, RedirectResponse } from "../errors/index.ts";
+import { NotFoundError, RedirectResponse, UnauthenticatedError, UnauthorizedError } from "../errors/index.ts";
 import type { PerRouteHead } from "../head-client/index.ts";
 import { applyPerRouteHeads } from "../head-client/index.ts";
 import {
@@ -23,9 +24,13 @@ import {
 	setHistoryIndex,
 } from "../history/index.ts";
 import { isChunkLoadError, isRenderFn } from "../internal.ts";
+import { KEEPALIVE_PATH, STORAGE_CHUNK_RELOAD } from "../protocol.ts";
 import type { LocaleConfig } from "../locale.ts";
+import { formatLocaleCookie } from "../locale/cookie.ts";
 import { warn } from "../logger.ts";
-import { fetchNDJSON } from "../ndjson-client/index.ts";
+import { fetchNDJSON, type NDJSONFetchResult } from "../ndjson-client/index.ts";
+import type { DeferredResolver } from "../state-parser/index.ts";
+import { hasRawDeferredMarkers, hydrateLoaderData } from "../state-parser/index.ts";
 import type {
 	FlareProviderContext,
 	InternalNavigateOptions,
@@ -56,7 +61,12 @@ function extractRootIdentity(virtualPath: string): string {
 interface InternalProviderContext extends FlareProviderContext {
 	_setNavigate?: (fn: (opts: InternalNavigateOptions) => Promise<void>) => void;
 	_setPrefetch?: (
-		fn: (opts: { params?: Record<string, unknown>; search?: Record<string, unknown>; to: string }) => Promise<void>,
+		fn: (opts: {
+			modulesOnly?: boolean;
+			params?: Record<string, unknown>;
+			search?: Record<string, unknown>;
+			to: string;
+		}) => Promise<void>,
 	) => void;
 }
 
@@ -110,24 +120,42 @@ let localeConfig: LocaleConfig | undefined;
 let directionConfig: DirectionConfig | undefined;
 const visitedRoutes = new Set<string>();
 
+/** In-flight hover/viewport prefetch — navigate reuses this instead of starting a second NDJSON. */
+const inflightPrefetch = new Map<string, { promise: Promise<NDJSONFetchResult>; startedAt: number }>();
+/** Resolvers for a painted prefetch `l` shell waiting on enter `c` chunks. */
+const deferredResumeResolvers = new Map<string, DeferredResolver>();
+
 /* Keepalive ping — keeps HTTP/2 connection and CF isolate warm */
 let keepaliveIntervalId: ReturnType<typeof setInterval> | null = null;
 let keepaliveVisibilityHandler: (() => void) | null = null;
 
 let clickCleanup: (() => void) | null = null;
 
-/* SPA navigation blocker — set by useBlocker, checked by navigate */
-let activeBlockerFn: (() => boolean) | null = null;
-let onBlockedCallback: (() => void) | null = null;
+/* SPA navigation blockers — stacked so a child's cleanup cannot null a parent */
+interface BlockerRegistration {
+	onBlocked: () => void;
+	when: () => boolean;
+}
+const blockers: BlockerRegistration[] = [];
 let pendingNavigation: InternalNavigateOptions | null = null;
 
-/** Reset navigation phase + clear controller in one place — used at all early-return sites */
+/** Reset navigation phase. Keep currentController so the next navigate can abort late streams. */
 function stopNavigation(): void {
 	if (ctx) {
 		ctx.setNavigationPhase("idle");
 		ctx.setViewTransition(null);
 	}
-	currentController = null;
+}
+
+function rejectDeferredResume(error: Error): void {
+	for (const r of deferredResumeResolvers.values()) {
+		try {
+			r.reject(error);
+		} catch {
+			/* already settled */
+		}
+	}
+	deferredResumeResolvers.clear();
 }
 
 /**
@@ -143,8 +171,9 @@ function syncLocale(params: Record<string, string | string[]>): void {
 	const effectiveLocale = (typeof val === "string" ? val : undefined) ?? localeConfig.defaultLocale;
 
 	/* Cookie — always write for localized routes to keep it current */
-	const cookieName = localeConfig.cookieName ?? "flare.locale";
-	document.cookie = `${cookieName}=${effectiveLocale}; path=/; max-age=31536000; samesite=lax`;
+	document.cookie = formatLocaleCookie(effectiveLocale, localeConfig.cookieName, {
+		https: location.protocol === "https:",
+	});
 
 	/* html lang */
 	document.documentElement.setAttribute("lang", effectiveLocale);
@@ -158,9 +187,25 @@ function syncLocale(params: Record<string, string | string[]>): void {
 	}
 }
 
-export function setActiveBlocker(when: (() => boolean) | null, onBlocked?: () => void): void {
-	activeBlockerFn = when;
-	onBlockedCallback = onBlocked ?? null;
+export function setActiveBlocker(when: (() => boolean) | null, onBlocked?: () => void): () => void {
+	if (when === null) {
+		blockers.length = 0;
+		return () => {};
+	}
+	const entry: BlockerRegistration = { onBlocked: onBlocked ?? (() => {}), when };
+	blockers.push(entry);
+	return () => {
+		const i = blockers.indexOf(entry);
+		if (i >= 0) blockers.splice(i, 1);
+	};
+}
+
+function findBlocking(): BlockerRegistration | undefined {
+	for (let i = blockers.length - 1; i >= 0; i--) {
+		const blocker = blockers[i];
+		if (blocker?.when()) return blocker;
+	}
+	return undefined;
 }
 
 export function clearPendingNavigation(): void {
@@ -344,12 +389,17 @@ export function setupNavigation(
 	gcIntervalId = setInterval(() => {
 		if (!ctx) return;
 		const now = Date.now();
+		const defaultGc = parseMilliseconds(ctx.routerCacheDefaults?.gcTime ?? GC_MAX_AGE);
+		const prefetchGc = parseMilliseconds(
+			ctx.routerCacheDefaults?.prefetchGcTime ?? ctx.routerCacheDefaults?.gcTime ?? GC_MAX_AGE,
+		);
 		for (const entry of ctx.matchCache.getAll()) {
-			if (now - entry.updatedAt > GC_MAX_AGE) {
+			const maxAge = entry.gcTime ?? defaultGc;
+			if (now - entry.updatedAt > maxAge) {
 				ctx.matchCache.delete(entry.matchId);
 			}
 		}
-		ctx.prefetchCache.cleanup(GC_MAX_AGE);
+		ctx.prefetchCache.cleanup(prefetchGc);
 	}, GC_INTERVAL);
 
 	/* Keepalive ping — clear previous before setting up */
@@ -362,7 +412,7 @@ export function setupNavigation(
 	const keepaliveMs = options.keepalive;
 	if (typeof keepaliveMs === "number" && keepaliveMs > 0) {
 		const ping = () => {
-			fetch("/_flare/keepalive", { priority: "low" }).catch(() => {});
+			fetch(KEEPALIVE_PATH, { priority: "low" }).catch(() => {});
 		};
 
 		keepaliveIntervalId = setInterval(ping, keepaliveMs);
@@ -406,6 +456,13 @@ function resolveNavigationUrl(options: InternalNavigateOptions): URL | null {
 }
 
 /** Save scroll position + push/replace history state. */
+function samePathAndSearch(url: URL, loc: { pathname: string; search: SearchParams }): boolean {
+	return (
+		url.pathname === loc.pathname &&
+		serializeSearchParams(parseSearchParams(url.searchParams)) === serializeSearchParams(loc.search)
+	);
+}
+
 function handleHistoryUpdate(
 	options: InternalNavigateOptions,
 	url: URL,
@@ -433,24 +490,163 @@ function handleHistoryUpdate(
 	currentHistoryKey = newState.key;
 }
 
+function matchIdForModule(
+	mod: LoadedRouteModule,
+	search: SearchParams,
+	params: Record<string, string | string[]>,
+): string {
+	const deps = mod.effectsConfig?.loaderDeps?.({ search }) ?? [];
+	return computeMatchId({
+		loaderDeps: () => deps,
+		params,
+		routeId: mod.virtualPath,
+		search,
+	});
+}
+
+function applyPrefetchMatches(navCtx: FlareProviderContext, fetchResult: NDJSONFetchResult, startedAt: number): void {
+	const headByMatchId = new Map<string, HeadConfig>();
+	for (const h of fetchResult.perRouteHeads) {
+		headByMatchId.set(h.matchId, h.head);
+	}
+	const now = Date.now();
+	for (const m of fetchResult.matches) {
+		const existing = navCtx.matchCache.get(m.matchId);
+		/* A newer navigate already committed this match — do not clobber it. */
+		if (existing && existing.updatedAt > startedAt) continue;
+		navCtx.matchCache.set({
+			data: m.loaderData,
+			error: m.error,
+			hasDeferred: m.hasDeferredMarkers,
+			headConfig: headByMatchId.get(m.matchId),
+			invalid: false,
+			matchId: m.matchId,
+			preloaderContext: m.preloaderContext,
+			updatedAt: now,
+		});
+	}
+}
+
+function routeHasDeferredShell(
+	allModules: LoadedRouteModule[],
+	search: SearchParams,
+	params: Record<string, string | string[]>,
+): boolean {
+	if (!ctx) return false;
+	for (const mod of allModules) {
+		if (ctx.matchCache.get(matchIdForModule(mod, search, params))?.hasDeferred) return true;
+	}
+	return false;
+}
+
+function hydrateCachedDeferred(cached: CachedMatch): boolean {
+	if (!ctx || !cached.hasDeferred || !hasRawDeferredMarkers(cached.data)) return false;
+	const matchCache = ctx.matchCache;
+	const local = new Map<string, DeferredResolver>();
+	cached.data = hydrateLoaderData(cached.matchId, cached.data, local);
+	if (local.size === 0) return false;
+	let remaining = local.size;
+	const matchId = cached.matchId;
+	for (const [key, r] of local) {
+		deferredResumeResolvers.set(key, {
+			reject(err) {
+				r.reject(err);
+				remaining--;
+				if (remaining <= 0) {
+					const cur = matchCache.get(matchId);
+					if (cur) {
+						cur.hasDeferred = false;
+						matchCache.set(cur);
+					}
+				}
+			},
+			resolve(data) {
+				r.resolve(data);
+				remaining--;
+				if (remaining <= 0) {
+					const cur = matchCache.get(matchId);
+					if (cur) {
+						cur.hasDeferred = false;
+						cur.updatedAt = Date.now();
+						matchCache.set(cur);
+					}
+				}
+			},
+		});
+	}
+	matchCache.set(cached);
+	return true;
+}
+
+/**
+ * Paint cached/prefetched matches immediately so click is not blocked on NDJSON.
+ * Hydrates prefetch `{ __deferred, key }` markers so Await can track enter `c` chunks.
+ */
+function commitCachedShell(
+	c: FlareProviderContext,
+	allModules: LoadedRouteModule[],
+	search: SearchParams,
+	params: Record<string, string | string[]>,
+): { hadShell: boolean; keepMatchIds: string[] } {
+	if (!ctx) return { hadShell: false, keepMatchIds: [] };
+	let found = false;
+	const heads: PerRouteHead[] = [];
+	const keepMatchIds: string[] = [];
+	for (const mod of allModules) {
+		const matchId = matchIdForModule(mod, search, params);
+		const cached = ctx.matchCache.get(matchId);
+		if (!cached || cached.invalid) continue;
+		found = true;
+		if (cached.hasDeferred && hydrateCachedDeferred(cached)) {
+			keepMatchIds.push(matchId);
+		}
+		if (cached.headConfig) heads.push({ head: cached.headConfig, matchId });
+	}
+	if (!found) return { hadShell: false, keepMatchIds: [] };
+
+	c.setIntercepted(null);
+	c.setNotFound(false);
+	assignMatches(c, buildClientMatches(allModules, search, params));
+	c.setParams(params);
+	c.setSearch(search);
+	syncLocale(params);
+	if (heads.length > 0) applyPerRouteHeads(heads);
+	return { hadShell: true, keepMatchIds };
+}
+
+function sameRouteParams(a: Record<string, string | string[]>, b: Record<string, string | string[]>): boolean {
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	for (const key of keys) {
+		const av = a[key];
+		const bv = b[key];
+		if (av === bv) continue;
+		if (Array.isArray(av) && Array.isArray(bv)) {
+			if (av.length !== bv.length) return false;
+			for (let i = 0; i < av.length; i++) {
+				if (av[i] !== bv[i]) return false;
+			}
+			continue;
+		}
+		return false;
+	}
+	return true;
+}
+
 /** Map loaded modules to client match objects using cached data. */
 function buildClientMatches(
 	allModules: LoadedRouteModule[],
 	search: SearchParams,
 	params: Record<string, string | string[]>,
 ) {
-	return allModules.map((mod) => {
-		const deps = mod.effectsConfig?.loaderDeps?.({ search }) ?? [];
-		const matchId = computeMatchId({
-			loaderDeps: () => deps,
-			params,
-			routeId: mod.virtualPath,
-			search,
-		});
+	const current = ctx?.matches() ?? [];
+	const paramsUnchanged = sameRouteParams(ctx?.params() ?? {}, params);
+	return allModules.map((mod, i) => {
+		const matchId = matchIdForModule(mod, search, params);
 		const cached = ctx?.matchCache.get(matchId);
 		const error = cached?.error instanceof Error ? cached.error : undefined;
 
-		return {
+		const next = {
 			_type: mod._type,
 			error,
 			errorRender: isRenderFn(mod.errorRender) ? mod.errorRender : undefined,
@@ -463,9 +659,39 @@ function buildClientMatches(
 			variablePath: mod.variablePath,
 			virtualPath: mod.virtualPath,
 		};
+		/* Reuse the previous object when the route slot is unchanged so
+		   Outlet <Show keyed when={match()}> does not remount (local page
+		   signals). Param changes are a new page instance — render bodies
+		   that snapshot loaderData (translators, query keys) must re-run.
+		   Search-only updates keep identity and refresh via matchesEpoch.
+		   Error identity must change — Errored stays in fallback if the same
+		   object is mutated from error to success. */
+		const prev = current[i];
+		if (
+			prev &&
+			paramsUnchanged &&
+			prev.virtualPath === next.virtualPath &&
+			prev._type === next._type &&
+			prev.error === next.error
+		) {
+			Object.assign(prev, next);
+			return prev;
+		}
+		return next;
 	});
 }
 
+function assignMatches(c: FlareProviderContext, next: ReturnType<FlareProviderContext["matches"]>): void {
+	const current = c.matches();
+	if (next.length === current.length && next.length > 0 && next.every((m, i) => m === current[i])) {
+		/* Reused objects: do not write matches (keeps Outlet from remounting
+		 * local page signals). Tick matchesEpoch so loader/t hooks re-read. */
+		c.touchMatches?.();
+		return;
+	}
+	c.setMatches(next);
+}
+
 /** Apply view transition with VT API, or call update() directly as fallback.
  * Returns a promise that resolves after update() has executed so navigate()
  * callers can rely on state being settled when the promise resolves.
@@ -585,14 +811,15 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 	const c = ctx;
 
 	/* Step 0: Check SPA blocker (skip for popstate — browser already changed URL) */
-	if (activeBlockerFn && !options._popstate && !options._bypassBlocker && activeBlockerFn()) {
-		pendingNavigation = options;
-		/* Defer to avoid re-entrant navigation from SolidJS reactive effects */
-		if (onBlockedCallback) {
-			const cb = onBlockedCallback;
+	if (!options._popstate && !options._bypassBlocker) {
+		const blocker = findBlocking();
+		if (blocker) {
+			pendingNavigation = options;
+			/* Defer to avoid re-entrant navigation from SolidJS reactive effects */
+			const cb = blocker.onBlocked;
 			queueMicrotask(() => cb());
+			return;
 		}
-		return;
 	}
 
 	/* Step 1: Resolve URL + same-URL guard */
@@ -601,6 +828,7 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 
 	/* Step 2: Abort previous + set navigating */
 	if (currentController) currentController.abort();
+	rejectDeferredResume(new DOMException("The operation was aborted", "AbortError"));
 	const controller = new AbortController();
 	currentController = controller;
 	navigationVersion++;
@@ -642,13 +870,12 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 						handleHistoryUpdate(options, url, partial.params);
 					}
 
-					batch(() => {
-						c.setNotFound(false);
-						c.setMatches(clientMatches);
-						c.setParams(partial.params);
-						c.setSearch(search);
-						stopNavigation();
-					});
+					c.setNotFound(false);
+					c.setMatches(clientMatches);
+					c.setParams(partial.params);
+					c.setSearch(search);
+					stopNavigation();
+
 					syncLocale(partial.params);
 					applyPerRouteHeads([{ head: { title: "Not Found" }, matchId: `${partial.route.x}/__notfound` }]);
 					return;
@@ -660,13 +887,12 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 			handleHistoryUpdate(options, url, {});
 		}
 
-		batch(() => {
-			c.setNotFound(true);
-			c.setMatches([]);
-			c.setParams({});
-			c.setSearch(parseSearchParams(url.searchParams));
-			stopNavigation();
-		});
+		c.setNotFound(true);
+		c.setMatches([]);
+		c.setParams({});
+		c.setSearch(parseSearchParams(url.searchParams));
+		stopNavigation();
+
 		applyPerRouteHeads([{ head: { title: "Not Found" }, matchId: "__notfound" }]);
 		return;
 	}
@@ -692,8 +918,20 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 	 * matches one of the "from" routes, render as overlay instead of full navigation. */
 	const interceptConfig = match.route.o.intercept;
 	if (interceptConfig && !options._popstate && !options.revalidate) {
-		const currentVarPath = ctx.location().variablePath;
-		if (interceptConfig.from.includes(currentVarPath)) {
+		const loc = ctx.location();
+		/* window.location is the overlay URL while loc is the frozen background. */
+		const displayed =
+			typeof window !== "undefined"
+				? {
+						pathname: window.location.pathname,
+						search: parseSearchParams(new URLSearchParams(window.location.search)),
+					}
+				: loc;
+		if (
+			!samePathAndSearch(url, loc) &&
+			!samePathAndSearch(url, displayed) &&
+			interceptConfig.from.includes(loc.variablePath)
+		) {
 			try {
 				/* Load modules + fetch data for the intercepted target */
 				const modules = await loadRouteModules(matchPath, ctx.routeTree, ctx.layouts);
@@ -709,17 +947,24 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 
 				/* Update matchCache with fetched data */
 				const now = Date.now();
+				const interceptTags = resolveCacheTags(modules.page.cache, modules.params);
+				const interceptHeads = new Map(fetchResult.perRouteHeads.map((h) => [h.matchId, h.head]));
 				for (const m of fetchResult.matches) {
 					ctx.matchCache.set({
 						data: m.loaderData,
 						error: m.error,
 						hasDeferred: m.hasDeferredMarkers,
+						headConfig: interceptHeads.get(m.matchId),
 						invalid: false,
 						matchId: m.matchId,
 						preloaderContext: m.preloaderContext,
+						tags: interceptTags,
 						updatedAt: now,
 					});
 				}
+				if (fetchResult.perRouteHeads.length > 0) {
+					applyPerRouteHeads(fetchResult.perRouteHeads);
+				}
 
 				/* Build single ClientMatch for the intercepted page */
 				const allModules: LoadedRouteModule[] = [modules.page];
@@ -749,10 +994,10 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 							if (typeof history !== "undefined") history.back();
 						},
 						match: interceptedMatch,
+						params: modules.params,
 						render: interceptConfig.render,
+						search,
 					});
-					c.setParams(modules.params);
-					c.setSearch(search);
 					syncLocale(modules.params);
 				}
 
@@ -765,27 +1010,39 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 		}
 	}
 
+	const previousPathname = typeof window !== "undefined" ? window.location.pathname : "/";
+	const previousSearch = typeof window !== "undefined" ? window.location.search : "";
+	const previousHash = typeof window !== "undefined" ? window.location.hash : "";
+	const previousIndex = getHistoryIndex();
+	const previousKey = currentHistoryKey;
+	const previousParams = ctx.location().params;
+
 	/* Step 4: Save scroll + update history (skip for popstate — handled in listener) */
 	if (!options._popstate) {
 		handleHistoryUpdate(options, url, match.params);
 	}
 
 	/* Step 4b: Hash-only change — skip loaders, just update hash + scroll.
-	 * Compare against ctx.location() since Step 4 already updated window.location.
-	 * Skip for popstate — browser already updated window.location, so ctx.location()
-	 * reads the new URL, making the comparison always match (false positive).
+	 * Compare only to the pre-Step-4 window URL. FlareProvider.location()
+	 * reads pathname from window, which handleHistoryUpdate already moved,
+	 * so using loc here treats every same-search path change as hash-only.
+	 * Overlay hash-only still matches: previousPathname is the overlay URL.
+	 * Skip for popstate — browser already updated window.location.
 	 * Skip when revalidate is set — caller explicitly wants loaders to re-run. */
 	if (!options._popstate && !options.revalidate) {
-		const loc = ctx.location();
-		const currentSearch = serializeSearchParams(loc.search);
-		if (url.pathname === loc.pathname && url.search === currentSearch) {
+		const previous = {
+			pathname: previousPathname,
+			search: parseSearchParams(new URLSearchParams(previousSearch)),
+		};
+		if (samePathAndSearch(url, previous)) {
 			const search = parseSearchParams(url.searchParams);
-			batch(() => {
+
+			if (!c.intercepted()) {
 				c.setIntercepted(null);
 				c.setParams(match.params);
 				c.setSearch(search);
-			});
-			syncLocale(match.params);
+				syncLocale(match.params);
+			}
 			if (url.hash) {
 				const el = typeof document !== "undefined" ? document.getElementById(url.hash.slice(1)) : null;
 				if (el) {
@@ -839,16 +1096,21 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 				warn("nav", `shallow validation failed: ${e instanceof Error ? e.message : String(e)}`);
 			}
 
-			batch(() => {
-				c.setParams(validatedParams);
-				c.setSearch(validatedSearch);
-				stopNavigation();
-			});
+			if (controller.signal.aborted || myVersion !== navigationVersion) return;
+
+			c.setParams(validatedParams);
+			c.setSearch(validatedSearch);
+			stopNavigation();
+
 			syncLocale(validatedParams);
 			return;
 		}
 	}
 
+	let paintedShell = false;
+	let paintedModules: LoadedRouteModule[] | undefined;
+	let paintedSearch: SearchParams | undefined;
+	let paintedParams: Record<string, string | string[]> | undefined;
 	try {
 		/* Step 6: Load route modules */
 		const isNewRoute = !visitedRoutes.has(match.route.x);
@@ -880,18 +1142,57 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 		const nonRootLayouts = modules.layouts.filter((m) => m._type !== "root-layout");
 		const allModules: LoadedRouteModule[] = [...nonRootLayouts, modules.page];
 
+		/* Instant navigation: reuse in-flight prefetch and paint a cached shell
+		 * before the enter NDJSON hop. Skipped when this nav already fetched in
+		 * parallel (first visit, no cache). */
+		let adoptedInflight = false;
+		let hadShell = false;
+		let keepMatchIds: string[] = [];
+		const sequential = !fetchResult;
+		if (!fetchResult) {
+			const inflight = inflightPrefetch.get(url.href);
+			if (inflight) {
+				try {
+					await inflight.promise;
+					adoptedInflight = true;
+				} catch {
+					/* Prefetch failed — navigate fetches below */
+				}
+			}
+			if (controller.signal.aborted || myVersion !== navigationVersion) return;
+			const shell = commitCachedShell(c, allModules, search, modules.params);
+			hadShell = shell.hadShell;
+			paintedShell = shell.hadShell;
+			if (shell.hadShell) {
+				paintedModules = allModules;
+				paintedSearch = search;
+				paintedParams = modules.params;
+			}
+			keepMatchIds = shell.keepMatchIds;
+			/* Restore before the next paint so back/forward does not flash at y=0
+			 * while the enter hop (or the post-update rAF) is still outstanding. */
+			if (hadShell && scrollRestorationEnabled) {
+				flush();
+				if (options._restoreScroll) {
+					restoreScroll(options._restoreScroll, "auto");
+				} else if (options.scroll !== false) {
+					if (url.hash) {
+						const el = typeof document !== "undefined" ? document.getElementById(url.hash.slice(1)) : null;
+						if (el) el.scrollIntoView();
+						else scrollToTop();
+					} else {
+						scrollToTop();
+					}
+				}
+			}
+		}
+
 		/* Step 7: Compute match IDs + check staleness (only for known-cached routes) */
 		if (!fetchResult) {
 			const staleMatchIds: string[] = [];
 
 			for (const mod of allModules) {
-				const deps = mod.effectsConfig?.loaderDeps?.({ search }) ?? [];
-				const matchId = computeMatchId({
-					loaderDeps: () => deps,
-					params: modules.params,
-					routeId: mod.virtualPath,
-					search,
-				});
+				const matchId = matchIdForModule(mod, search, modules.params);
 
 				const cc = mod.cache?.client;
 				const staleTime =
@@ -925,17 +1226,28 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 				}
 			}
 
+			/* In-flight prefetch *is* the navigation fetch for non-deferred
+			 * shells. Deferred still needs an enter hop to stream `c` chunks. */
+			const skipEnterFetch =
+				adoptedInflight && !options.revalidate && !routeHasDeferredShell(allModules, search, modules.params);
+
 			/* Step 8: Fetch if needed */
-			if (staleMatchIds.length > 0) {
+			if (!skipEnterFetch && staleMatchIds.length > 0) {
 				fetchResult = await fetchNDJSON({
+					keepMatchIds: keepMatchIds.length > 0 ? keepMatchIds : undefined,
 					matchIds: staleMatchIds,
 					queryClient: queryClientRef,
+					resolvers: keepMatchIds.length > 0 ? deferredResumeResolvers : undefined,
 					signal: controller.signal,
 					url: url.href,
 				});
 			}
 		}
 
+		if (import.meta.env.DEV && sequential && !hadShell && fetchResult && !options._popstate) {
+			warn("nav", `navigation to ${url.pathname} waited on loaders with no prefetched shell`);
+		}
+
 		if (controller.signal.aborted || myVersion !== navigationVersion) return;
 
 		/* Step 9: Update matchCache (includes headConfig for per-route head management) */
@@ -962,8 +1274,19 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 			}
 
 			const now = Date.now();
+			const gcByMatchId = new Map<string, number>();
+			const tagsByMatchId = new Map<string, string[]>();
+			for (const mod of allModules) {
+				const id = matchIdForModule(mod, search, modules.params);
+				const cc = mod.cache?.client;
+				if (cc !== false && cc !== undefined && cc.gcTime !== undefined) {
+					gcByMatchId.set(id, parseMilliseconds(cc.gcTime));
+				}
+				const tags = resolveCacheTags(mod.cache, modules.params);
+				if (tags) tagsByMatchId.set(id, tags);
+			}
 			for (const m of fetchResult.matches) {
-				/* x-m skip runs the route with loader stripped → null data.
+				/* flare-stale skip runs the route with loader stripped → null data.
 				   Do not clobber a live cache entry that already has data. */
 				const existing = ctx.matchCache.get(m.matchId);
 				if (m.loaderData == null && !m.error && existing && existing.data != null) {
@@ -974,14 +1297,26 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 					}
 					continue;
 				}
+				/* Prefetch `l` hydrated this nav — keep it, let `c` fill Await.
+				 * Do not keep a leftover hasDeferred entry: abort leaves dead promises. */
+				if (!options.revalidate && existing && !m.error && m.keepShell) {
+					const nextHead = headByMatchId.get(m.matchId);
+					if (nextHead) {
+						existing.headConfig = nextHead;
+						ctx.matchCache.set(existing);
+					}
+					continue;
+				}
 				ctx.matchCache.set({
 					data: m.loaderData,
 					error: m.error,
+					gcTime: gcByMatchId.get(m.matchId),
 					hasDeferred: m.hasDeferredMarkers,
 					headConfig: headByMatchId.get(m.matchId),
 					invalid: false,
 					matchId: m.matchId,
 					preloaderContext: m.preloaderContext,
+					tags: tagsByMatchId.get(m.matchId),
 					updatedAt: now,
 				});
 
@@ -1007,12 +1342,45 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 			}
 		}
 
-		/* Failed data fetch with no parsed matches: keep the current match
-		 * tree. Rebuilding from cache would drop pipeline errors that were
-		 * never written to matchCache (SSR hydrates them via errorName only). */
+		/* Bare HTTP error with no NDJSON matches. 401/403 commit auth
+		 * boundaries; other 4xx/5xx commit a pipeline error so invalid
+		 * params and loader failures stay on the target URL. Network-level
+		 * failures (no status) revert — do not leave the address bar on a
+		 * path whose tree never committed. */
 		if (fetchResult && fetchResult.success === false && fetchResult.matches.length === 0) {
-			stopNavigation();
-			return;
+			const status = fetchResult.status;
+			const err =
+				status === 401
+					? new UnauthenticatedError()
+					: status === 403
+						? new UnauthorizedError()
+						: typeof status === "number" && status >= 400
+							? new Error(`Request failed (${status})`)
+							: undefined;
+			if (err) {
+				const last = allModules.at(-1);
+				if (last) {
+					ctx.matchCache.set({
+						data: null,
+						error: err,
+						hasDeferred: false,
+						invalid: false,
+						matchId: matchIdForModule(last, search, modules.params),
+						updatedAt: Date.now(),
+					});
+				}
+			} else {
+				if (!options._popstate && !hadShell) {
+					replaceHistoryState(previousPathname, previousParams, previousSearch, {
+						hash: previousHash,
+						historyIndex: previousIndex,
+					});
+					currentHistoryKey = previousKey;
+					setHistoryIndex(previousIndex);
+				}
+				stopNavigation();
+				return;
+			}
 		}
 
 		/* Step 10: Build client matches */
@@ -1042,36 +1410,52 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 		/* Step 12: Update state + scroll + head + cleanup.
 		 * Everything inside update() so VT captures the complete state transition. */
 		const update = () => {
-			batch(() => {
-				c.setIntercepted(null);
-				c.setNotFound(false);
-				c.setMatches(clientMatches);
-				c.setParams(modules.params);
-				c.setSearch(search);
-			});
+			if (myVersion !== navigationVersion) return;
+			c.setIntercepted(null);
+			c.setNotFound(false);
+			assignMatches(c, clientMatches);
+			c.setParams(modules.params);
+			c.setSearch(search);
+
 			syncLocale(modules.params);
 
-			/* Popstate scroll restoration — double rAF ensures SolidJS has flushed its
-			 * reactive updates and the DOM is ready before we scroll.
-			 * Version check prevents stale restore when a new navigation supersedes this one. */
+			/* Popstate scroll restoration. A cached shell already restored in the
+			 * same turn as setMatches; restore again after this commit in case the
+			 * fetched tree changed height. Skip rAF on that path — rAF is after paint
+			 * and would flash y=0. No-shell popstate still waits for layout via rAF. */
 			if (scrollRestorationEnabled && options._restoreScroll !== undefined) {
-				requestAnimationFrame(() => {
+				if (hadShell && options._restoreScroll) {
+					flush();
+					restoreScroll(options._restoreScroll, "auto");
+				} else {
 					requestAnimationFrame(() => {
-						if (myVersion !== navigationVersion) return;
-						if (options._restoreScroll) {
-							restoreScroll(options._restoreScroll, scrollRestorationBehavior);
-						} else {
-							scrollToTop();
-						}
+						requestAnimationFrame(() => {
+							if (myVersion !== navigationVersion) return;
+							if (options._restoreScroll) {
+								restoreScroll(options._restoreScroll, scrollRestorationBehavior);
+							} else {
+								scrollToTop();
+							}
+						});
 					});
-				});
+				}
 			} else if (options.scroll !== false) {
 				if (url.hash) {
-					const el = typeof document !== "undefined" ? document.getElementById(url.hash.slice(1)) : null;
+					flush();
+					const id = url.hash.slice(1);
+					const el = typeof document !== "undefined" ? document.getElementById(id) : null;
 					if (el) {
 						el.scrollIntoView();
 					} else {
-						scrollToTop();
+						/* Solid 2 may not have committed the new route yet. */
+						requestAnimationFrame(() => {
+							requestAnimationFrame(() => {
+								if (myVersion !== navigationVersion) return;
+								const late = typeof document !== "undefined" ? document.getElementById(id) : null;
+								if (late) late.scrollIntoView();
+								else scrollToTop();
+							});
+						});
 					}
 				} else {
 					scrollToTop();
@@ -1116,7 +1500,7 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 		}
 		if (isChunkLoadError(error) && typeof window !== "undefined") {
 			try {
-				const key = "__flare_chunk_reload__";
+				const key = STORAGE_CHUNK_RELOAD;
 				const last = Number(sessionStorage.getItem(key) || 0);
 				if (Date.now() - last > 10_000) {
 					sessionStorage.setItem(key, String(Date.now()));
@@ -1124,12 +1508,25 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 					return;
 				}
 			} catch {
-				/* sessionStorage unavailable — reload once without guard */
-				window.location.reload();
-				return;
+				/* No durable guard — a reload would loop in private mode. */
 			}
 			/* Already reloaded recently — don't loop, let the error propagate */
 		}
+		if (paintedShell && ctx && paintedModules && paintedSearch && paintedParams) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			const last = paintedModules.at(-1);
+			if (last) {
+				ctx.matchCache.set({
+					data: null,
+					error: err,
+					hasDeferred: false,
+					invalid: false,
+					matchId: matchIdForModule(last, paintedSearch, paintedParams),
+					updatedAt: Date.now(),
+				});
+			}
+			rejectDeferredResume(err);
+		}
 		stopNavigation();
 		throw error;
 	}
@@ -1137,7 +1534,17 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 
 const DEFAULT_PREFETCH_STALE_TIME = 30_000;
 
+function matchCacheHasFreshRoute(routeId: string, staleTime: number): boolean {
+	if (!ctx) return false;
+	for (const entry of ctx.matchCache.getAll()) {
+		if (entry.matchId !== routeId && !entry.matchId.startsWith(`${routeId}:`)) continue;
+		if (!ctx.matchCache.isStale(entry.matchId, staleTime)) return true;
+	}
+	return false;
+}
+
 export async function prefetch(options: {
+	modulesOnly?: boolean;
 	params?: Record<string, unknown>;
 	search?: Record<string, unknown>;
 	to: string;
@@ -1152,46 +1559,84 @@ export async function prefetch(options: {
 	const match = matchRoute(ctx.routeTree, rewritePathname(url.pathname), caseSensitive, toLocaleMatch(localeConfig));
 	if (!match) return;
 
+	const navCtx = ctx;
+	const loadMods = loadRouteModules;
+	if (!navCtx || !loadMods) return;
+
+	/* Viewport/render: warm JS once per route. Do not NDJSON every URL. */
+	if (options.modulesOnly) {
+		visitedRoutes.add(match.route.x);
+		try {
+			await loadMods(rewritePathname(url.pathname), navCtx.routeTree, navCtx.layouts);
+		} catch {
+			/* Speculative */
+		}
+		return;
+	}
+
 	const staleTime = parseMilliseconds(
 		match?.route.o.client?.prefetchStaleTime ??
 			ctx?.routerCacheDefaults?.prefetchStaleTime ??
 			DEFAULT_PREFETCH_STALE_TIME,
 	);
 
-	if (!ctx.prefetchCache.shouldPrefetch(url.href, staleTime)) return;
+	const inflight = inflightPrefetch.get(url.href);
+	if (inflight) {
+		try {
+			await inflight.promise;
+		} catch {
+			/* Speculative */
+		}
+		return;
+	}
 
-	try {
-		const [fetchResult] = await Promise.all([
-			fetchNDJSON({ prefetch: true, queryClient: queryClientRef, url: url.href }),
-			loadRouteModules(rewritePathname(url.pathname), ctx.routeTree, ctx.layouts),
-		]);
+	if (!ctx.prefetchCache.shouldPrefetch(url.href, staleTime)) return;
 
+	/* Hover/viewport prefetch must not refetch a route still inside client
+	   staleTime — that overwrites matchCache and looks like a cache miss. */
+	const clientStaleTime = parseMilliseconds(match.route.o.client?.staleTime ?? ctx.routerCacheDefaults?.staleTime ?? 0);
+	if (clientStaleTime > 0 && matchCacheHasFreshRoute(match.route.x, clientStaleTime)) {
+		visitedRoutes.add(match.route.x);
 		ctx.prefetchCache.mark(url.href);
+		return;
+	}
+
+	/* Mark visited immediately so a click during in-flight prefetch does not
+	   take navigate()'s parallel-fetch "new route" path. */
+	visitedRoutes.add(match.route.x);
 
-		/* Mark route visited so navigate() checks staleness instead of blind re-fetch */
-		if (match) visitedRoutes.add(match.route.x);
+	const startedAt = Date.now();
+	const resultPromise = fetchNDJSON({ prefetch: true, queryClient: queryClientRef, url: url.href }).then(
+		(fetchResult) => {
+			applyPrefetchMatches(navCtx, fetchResult, startedAt);
+			return fetchResult;
+		},
+	);
+	inflightPrefetch.set(url.href, { promise: resultPromise, startedAt });
 
-		const headByMatchId = new Map<string, HeadConfig>();
-		for (const h of fetchResult.perRouteHeads) {
-			headByMatchId.set(h.matchId, h.head);
+	try {
+		const [fetchResult, modules] = await Promise.all([
+			resultPromise,
+			loadMods(rewritePathname(url.pathname), navCtx.routeTree, navCtx.layouts),
+		]);
+		if (fetchResult.success !== false) {
+			navCtx.prefetchCache.mark(url.href);
 		}
-		const now = Date.now();
-		for (const m of fetchResult.matches) {
-			ctx.matchCache.set({
-				data: m.loaderData,
-				error: m.error,
-				hasDeferred: m.hasDeferredMarkers,
-				headConfig: headByMatchId.get(m.matchId),
-				invalid: false,
-				matchId: m.matchId,
-				preloaderContext: m.preloaderContext,
-				updatedAt: now,
-			});
+		if (modules) {
+			const nonRoot = modules.layouts.filter((m) => m._type !== "root-layout");
+			applyMatchCacheTags(
+				navCtx.matchCache,
+				[...nonRoot, modules.page],
+				modules.params,
+				parseSearchParams(url.searchParams),
+			);
 		}
 	} catch {
 		/* Silently discard errors including redirects — prefetch is speculative
 		 * (hover/touch). Navigating on redirect would move the user away from
 		 * the current page before they actually click the link. */
+	} finally {
+		inflightPrefetch.delete(url.href);
 	}
 }
 
@@ -1219,8 +1664,9 @@ export function resetNavigationState(): void {
 		deferredTracker = null;
 	}
 	visitedRoutes.clear();
-	activeBlockerFn = null;
-	onBlockedCallback = null;
+	inflightPrefetch.clear();
+	deferredResumeResolvers.clear();
+	blockers.length = 0;
 	pendingNavigation = null;
 	if (popstateCleanup) {
 		popstateCleanup();