@pracht/core 0.8.1 → 0.9.0

package/dist/prefetch-api-Bf-P7XFo.d.mts

@@ -0,0 +1,39 @@
+import { J as RouteId, at as RouteTarget } from "./types-B-sfVjaH.mjs";
+import { FunctionComponent } from "preact";
+
+//#region src/forwardRef.d.ts
+/**
+ * Pass ref down to a child. This is mainly used in libraries with HOCs that
+ * wrap components. Using `forwardRef` there is an easy way to get a reference
+ * of the wrapped component instead of one of the wrapper itself.
+ */
+declare function forwardRef<P = {}>(fn: ((props: P, ref: any) => any) & {
+  displayName?: string;
+}): FunctionComponent<P & {
+  ref?: any;
+}>;
+//#endregion
+//#region src/hydration.d.ts
+/**
+ * Returns `true` once the initial hydration (including all Suspense
+ * boundaries) has fully resolved. During SSR and hydration this returns
+ * `false`.
+ */
+declare function useIsHydrated(): boolean;
+//#endregion
+//#region src/prefetch-api.d.ts
+interface PrefetchFn {
+  (to: string): Promise<void>;
+  <TRoute extends RouteId>(to: RouteTarget<TRoute>): Promise<void>;
+}
+/**
+ * Imperatively prefetch a route: warms the route/shell module chunks and
+ * caches the route-state JSON in the shared prefetch cache. Accepts an href
+ * string or a typed route target (`{ route, params, search }`).
+ *
+ * Available once the client router has initialized; a no-op during SSR,
+ * before hydration, and for URLs that do not match a client route.
+ */
+declare const prefetch: PrefetchFn;
+//#endregion
+export { forwardRef as i, prefetch as n, useIsHydrated as r, PrefetchFn as t };

package/dist/prefetch-api-ChSCTbEB.mjs

@@ -0,0 +1,69 @@
+import { o as matchAppRoute, t as buildHref } from "./app-CGRKjZ6Z.mjs";
+import { a as removeCachedRouteState, c as fetchPrachtRouteState, d as routeNeedsServerFetch, i as getCachedRouteState, n as cacheRouteState, t as EMPTY_ROUTE_STATE_PROMISE } from "./prefetch-cache-BNLEp9H5.mjs";
+//#region src/prefetch-api.ts
+/**
+* Imperative prefetch surface shared by the lazy prefetch listeners
+* (`prefetch.ts`), the client router, and userland code via the public
+* `prefetch()` export. Kept separate from `prefetch.ts` so importing the
+* public API does not pull the document-level listener setup into the
+* critical hydration path — every module imported here is already part of
+* the core client bundle.
+*/
+let activePrefetchTarget = null;
+/**
+* Called by the client router during initialization so prefetching can match
+* URLs against the resolved app and warm route/shell module chunks.
+*/
+function registerPrefetchTarget(app, warmModules) {
+	activePrefetchTarget = {
+		app,
+		warmModules
+	};
+}
+/**
+* Fetch (or reuse) the route-state JSON for `url` and store it in the shared
+* bounded prefetch cache so a subsequent client navigation can consume it
+* without a second network request. Rejected fetches are evicted from the
+* cache so a transient network error does not poison later navigations.
+*/
+function prefetchRouteState(url, route) {
+	if (route && !routeNeedsServerFetch(route)) return EMPTY_ROUTE_STATE_PROMISE;
+	const cached = getCachedRouteState(url);
+	if (cached) return cached;
+	const promise = fetchPrachtRouteState(url);
+	cacheRouteState(url, promise);
+	promise.catch(() => removeCachedRouteState(url, promise));
+	return promise;
+}
+/**
+* Imperatively prefetch a route: warms the route/shell module chunks and
+* caches the route-state JSON in the shared prefetch cache. Accepts an href
+* string or a typed route target (`{ route, params, search }`).
+*
+* Available once the client router has initialized; a no-op during SSR,
+* before hydration, and for URLs that do not match a client route.
+*/
+const prefetch = async (to) => {
+	if (typeof window === "undefined") return;
+	const target = activePrefetchTarget;
+	if (!target) return;
+	let href;
+	try {
+		href = typeof to === "string" ? to : buildHref(target.app.routes, to.route, to);
+	} catch {
+		return;
+	}
+	let url;
+	try {
+		url = new URL(href, window.location.href);
+	} catch {
+		return;
+	}
+	if (url.origin !== window.location.origin) return;
+	const match = matchAppRoute(target.app, url.pathname);
+	if (!match) return;
+	target.warmModules?.(match);
+	await prefetchRouteState(url.pathname + url.search, match.route).catch(() => {});
+};
+//#endregion
+export { prefetchRouteState as n, registerPrefetchTarget as r, prefetch as t };

package/dist/{prefetch-cache-DzP2Bj9H.mjs → prefetch-cache-BNLEp9H5.mjs}

@@ -4,6 +4,9 @@ const HYDRATION_STATE_ELEMENT_ID = "pracht-state";
 const ROUTE_STATE_REQUEST_HEADER = "x-pracht-route-state-request";
 const ROUTE_STATE_CACHE_CONTROL = "no-store";
 const EMPTY_ROUTE_PARAMS = {};
+const PREFETCH_ATTRIBUTE = "data-pracht-prefetch";
+const PRESERVE_SCROLL_ATTRIBUTE = "data-pracht-preserve-scroll";
+const VIEW_TRANSITION_ATTRIBUTE = "data-pracht-view-transition";
 //#endregion
 //#region src/runtime-client-fetch.ts
 const SAFE_NAVIGATION_PROTOCOLS = new Set(["http:", "https:"]);
@@ -115,6 +118,14 @@ function cacheRouteState(url, promise) {
 	});
 	trimMapToSize(prefetchCache, MAX_PREFETCH_CACHE_ENTRIES);
 }
+/**
+* Remove a cached entry, but only when it still holds `promise` — a newer
+* entry cached under the same URL must not be evicted by an older rejection.
+*/
+function removeCachedRouteState(url, promise) {
+	const entry = prefetchCache.get(url);
+	if (entry && entry.promise === promise) prefetchCache.delete(url);
+}
 function sweepPrefetchCache(now = Date.now()) {
 	for (const [url, entry] of prefetchCache) if (now - entry.timestamp > CACHE_TTL_MS) prefetchCache.delete(url);
 }
@@ -126,4 +137,4 @@ function trimMapToSize(map, maxEntries) {
 	}
 }
 //#endregion
-export { trimMapToSize as a, navigateToClientLocation as c, EMPTY_ROUTE_PARAMS as d, HYDRATION_STATE_ELEMENT_ID as f, SAFE_METHODS as h, getCachedRouteState as i, parseSafeNavigationUrl as l, ROUTE_STATE_REQUEST_HEADER as m, cacheRouteState as n, buildRouteStateUrl as o, ROUTE_STATE_CACHE_CONTROL as p, clearPrefetchCache as r, fetchPrachtRouteState as s, EMPTY_ROUTE_STATE_PROMISE as t, routeNeedsServerFetch as u };
+export { ROUTE_STATE_REQUEST_HEADER as _, removeCachedRouteState as a, fetchPrachtRouteState as c, routeNeedsServerFetch as d, EMPTY_ROUTE_PARAMS as f, ROUTE_STATE_CACHE_CONTROL as g, PRESERVE_SCROLL_ATTRIBUTE as h, getCachedRouteState as i, navigateToClientLocation as l, PREFETCH_ATTRIBUTE as m, cacheRouteState as n, trimMapToSize as o, HYDRATION_STATE_ELEMENT_ID as p, clearPrefetchCache as r, buildRouteStateUrl as s, EMPTY_ROUTE_STATE_PROMISE as t, parseSafeNavigationUrl as u, SAFE_METHODS as v, VIEW_TRANSITION_ATTRIBUTE as y };

package/dist/{prerender-B8_CqYwd.d.mts → prerender-BV42B9jK.d.mts}

@@ -1,4 +1,27 @@
-import { H as ModuleRegistry, W as PrachtApp, X as ResolvedApiRoute, lt as RouteRevalidate } from "./app-BWriseLj.mjs";
+import { F as PrachtApp, N as ModuleRegistry, V as ResolvedApiRoute, nt as RouteRevalidate } from "./types-B-sfVjaH.mjs";
+//#region src/runtime-timing.d.ts
+/**
+ * Per-request phase timing for dev tooling.
+ *
+ * The runtime only records durations when a collector object is passed via
+ * `HandlePrachtRequestOptions.timings` — the dev server passes one, production
+ * adapters never do, so production requests skip all timing work.
+ */
+interface PrachtPhaseTimings {
+  /** Milliseconds spent in the middleware chain, excluding loader and render. */
+  mw?: number;
+  /** Milliseconds spent awaiting the route loader. */
+  loader?: number;
+  /** Milliseconds spent resolving modules and rendering the response, excluding the loader. */
+  render?: number;
+}
+/**
+ * Format collected phase timings as a standards-compliant `Server-Timing`
+ * header value, e.g. `mw;dur=1.2, loader;dur=14.8, render;dur=3.1`.
+ * Returns an empty string when nothing was recorded.
+ */
+declare function formatServerTimingHeader(timings: PrachtPhaseTimings): string;
+//#endregion
 //#region src/runtime-headers.d.ts
 declare function applyDefaultSecurityHeaders(headers: Headers): Headers;
 //#endregion
@@ -16,6 +39,12 @@ interface HandlePrachtRequestOptions<TContext = unknown> {
   /** Per-source-file JS chunk map produced by the vite plugin for modulepreload hints. */
   jsManifest?: Record<string, string[]>;
   apiRoutes?: ResolvedApiRoute[];
+  /**
+   * Dev-only phase-timing collector. When provided, the runtime records
+   * middleware/loader/render durations (ms) onto it so callers can emit a
+   * `Server-Timing` header. Leave unset in production — no timing work runs.
+   */
+  timings?: PrachtPhaseTimings;
 }
 declare function handlePrachtRequest<TContext>(options: HandlePrachtRequestOptions<TContext>): Promise<Response>;
 //#endregion
@@ -48,4 +77,4 @@ declare function prerenderApp(options: PrerenderAppOptions & {
   withISGManifest: true;
 }): Promise<PrerenderAppResult>;
 //#endregion
-export { prerenderApp as a, applyDefaultSecurityHeaders as c, PrerenderResult as i, PrerenderAppOptions as n, HandlePrachtRequestOptions as o, PrerenderAppResult as r, handlePrachtRequest as s, ISGManifestEntry as t };
+export { prerenderApp as a, applyDefaultSecurityHeaders as c, PrerenderResult as i, PrachtPhaseTimings as l, PrerenderAppOptions as n, HandlePrachtRequestOptions as o, PrerenderAppResult as r, handlePrachtRequest as s, ISGManifestEntry as t, formatServerTimingHeader as u };

package/dist/{prerender-CoMyuJKm.mjs → prerender-C8BpANz3.mjs}

@@ -1,7 +1,7 @@
-import { a as matchApiRoute, c as resolveApp, n as buildPathFromSegments, o as matchAppRoute } from "./app-w-P1wf5T.mjs";
-import { _ as applyDefaultSecurityHeaders, b as withDefaultSecurityHeaders, c as mergeDocumentHeaders, d as runMiddlewareChain, f as resolveDataFunctions, g as appendVaryHeader, h as resolveRegistryModule, l as mergeHeadMetadata, m as resolvePageJsUrls, p as resolvePageCssUrls, v as applyHeaders, x as withRouteResponseHeaders, y as applySecurityAndRouteHeaders } from "./types-DQv2poC5.mjs";
-import { f as HYDRATION_STATE_ELEMENT_ID, h as SAFE_METHODS, m as ROUTE_STATE_REQUEST_HEADER, o as buildRouteStateUrl } from "./prefetch-cache-DzP2Bj9H.mjs";
-import { a as buildRuntimeDiagnostics, c as normalizeRouteError, l as shouldExposeServerErrors, o as createSerializedRouteError, s as deserializeRouteError, t as PrachtRuntimeProvider } from "./runtime-context-B5pREhcM.mjs";
+import { a as matchApiRoute, c as resolveApp, n as buildPathFromSegments, o as matchAppRoute } from "./app-CGRKjZ6Z.mjs";
+import { S as withRouteResponseHeaders, _ as appendVaryHeader, b as applySecurityAndRouteHeaders, f as runMiddlewareChain, g as resolveRegistryModule, h as resolvePageJsUrls, l as mergeDocumentHeaders, m as resolvePageCssUrls, p as resolveDataFunctions, u as mergeHeadMetadata, v as applyDefaultSecurityHeaders, x as withDefaultSecurityHeaders, y as applyHeaders } from "./types-DEPXdbyp.mjs";
+import { _ as ROUTE_STATE_REQUEST_HEADER, p as HYDRATION_STATE_ELEMENT_ID, s as buildRouteStateUrl, v as SAFE_METHODS } from "./prefetch-cache-BNLEp9H5.mjs";
+import { d as buildRuntimeDiagnostics, f as createSerializedRouteError, h as shouldExposeServerErrors, m as normalizeRouteError, p as deserializeRouteError, s as PrachtRuntimeProvider } from "./navigation-state-BjwXTeVz.mjs";
 import { h } from "preact";
 //#region src/runtime-html.ts
 function escapeHtml(str) {
@@ -260,6 +260,29 @@ function markdownResponse(source, initHeaders) {
 	});
 }
 //#endregion
+//#region src/runtime-timing.ts
+const PHASE_ORDER = [
+	"mw",
+	"loader",
+	"render"
+];
+/**
+* Format collected phase timings as a standards-compliant `Server-Timing`
+* header value, e.g. `mw;dur=1.2, loader;dur=14.8, render;dur=3.1`.
+* Returns an empty string when nothing was recorded.
+*/
+function formatServerTimingHeader(timings) {
+	const entries = [];
+	for (const phase of PHASE_ORDER) {
+		const duration = timings[phase];
+		if (typeof duration === "number" && Number.isFinite(duration)) entries.push(`${phase};dur=${formatDuration(duration)}`);
+	}
+	return entries.join(", ");
+}
+function formatDuration(duration) {
+	return String(Math.max(0, Math.round(duration * 10) / 10));
+}
+//#endregion
 //#region src/runtime.ts
 const SAME_ORIGIN_FETCH_SITE = "same-origin";
 /**
@@ -431,6 +454,7 @@ async function handlePrachtRequest(options) {
 	let shellModule;
 	let loaderFile;
 	let currentPhase = "middleware";
+	const timings = options.timings;
 	try {
 		const routeModulePromise = resolveRegistryModule(registry.routeModules, match.route.file);
 		const shellModulePromise = match.route.shellFile ? resolveRegistryModule(registry.shellModules, match.route.shellFile) : Promise.resolve(void 0);
@@ -445,7 +469,12 @@ async function handlePrachtRequest(options) {
 			currentPhase = "loader";
 			const { loader, loaderFile: resolvedLoaderFile } = await dataFunctionsPromise;
 			loaderFile = resolvedLoaderFile;
-			const loaderResult = loader ? await loader(routeArgs) : void 0;
+			let loaderResult;
+			if (loader) {
+				const loaderStart = timings ? performance.now() : 0;
+				loaderResult = await loader(routeArgs);
+				if (timings) timings.loader = performance.now() - loaderStart;
+			}
 			if (loaderResult instanceof Response) return loaderResult;
 			const data = loaderResult;
 			if (isRouteStateRequest) return Response.json({ data });
@@ -517,7 +546,20 @@ async function handlePrachtRequest(options) {
 				modulePreloadUrls
 			}), 200, documentHeaders);
 		};
-		return normalizePageResponse(await runMiddlewareChain({
+		let terminal = pageTerminal;
+		let chainStart = 0;
+		if (timings) {
+			terminal = async () => {
+				const terminalStart = performance.now();
+				try {
+					return await pageTerminal();
+				} finally {
+					timings.render = performance.now() - terminalStart - (timings.loader ?? 0);
+				}
+			};
+			chainStart = performance.now();
+		}
+		const response = await runMiddlewareChain({
 			context: pageContext,
 			middlewareFiles: match.route.middlewareFiles,
 			params: match.params,
@@ -526,8 +568,10 @@ async function handlePrachtRequest(options) {
 			route: match.route,
 			signal: requestSignal,
 			url,
-			terminal: pageTerminal
-		}), { isRouteStateRequest });
+			terminal
+		});
+		if (timings) timings.mw = performance.now() - chainStart - (timings.render ?? 0) - (timings.loader ?? 0);
+		return normalizePageResponse(response, { isRouteStateRequest });
 	} catch (error) {
 		return renderRouteErrorResponse({
 			error,
@@ -643,4 +687,4 @@ async function collectSSGPaths(route, registry) {
 	return (await routeModule.getStaticPaths()).map((params) => buildPathFromSegments(route.segments, params));
 }
 //#endregion
-export { handlePrachtRequest as n, prerenderApp as t };
+export { handlePrachtRequest as n, formatServerTimingHeader as r, prerenderApp as t };

package/dist/{router-BcUmg1kB.d.mts → router-B_Aj5TtY.d.mts}

@@ -1,5 +1,5 @@
-import { U as NavigateOptions, Z as ResolvedPrachtApp, dt as RouteTarget, nt as RouteId } from "./app-BWriseLj.mjs";
-import { t as PrachtHydrationState } from "./runtime-context-ytVd7GmZ.mjs";
+import { H as ResolvedPrachtApp, J as RouteId, P as NavigateOptions, at as RouteTarget } from "./types-B-sfVjaH.mjs";
+import { t as PrachtHydrationState } from "./runtime-context-BYBwVA0M.mjs";
 
 //#region src/router.d.ts
 declare global {

package/dist/{router-BkkyNjqB.mjs → router-E5Wh-dOR.mjs}

@@ -1,8 +1,9 @@
-import { o as matchAppRoute, t as buildHref } from "./app-w-P1wf5T.mjs";
-import { i as getCachedRouteState, l as parseSafeNavigationUrl, s as fetchPrachtRouteState, u as routeNeedsServerFetch } from "./prefetch-cache-DzP2Bj9H.mjs";
-import { s as deserializeRouteError, t as PrachtRuntimeProvider } from "./runtime-context-B5pREhcM.mjs";
+import { o as matchAppRoute, t as buildHref } from "./app-CGRKjZ6Z.mjs";
+import { c as fetchPrachtRouteState, d as routeNeedsServerFetch, i as getCachedRouteState, u as parseSafeNavigationUrl } from "./prefetch-cache-BNLEp9H5.mjs";
+import { a as settleNavigation, p as deserializeRouteError, r as createNavigationLocation, s as PrachtRuntimeProvider, t as beginLoadingNavigation } from "./navigation-state-BjwXTeVz.mjs";
+import { r as registerPrefetchTarget } from "./prefetch-api-ChSCTbEB.mjs";
 import { createContext, h, hydrate, options, render } from "preact";
-import { useContext, useEffect, useMemo, useState } from "preact/hooks";
+import { useContext, useEffect, useLayoutEffect, useMemo, useState } from "preact/hooks";
 import { Suspense } from "preact-suspense";
 //#region src/hydration.ts
 const MODE_HYDRATE$1 = 32;
@@ -200,6 +201,92 @@ function getVNodeName(vnode) {
 	return "Unknown";
 }
 //#endregion
+//#region src/scroll-restoration.ts
+const STORAGE_KEY = "pracht:scroll-positions";
+const MAX_SCROLL_ENTRIES = 50;
+const HISTORY_STATE_KEY = "__prachtScrollKey";
+function readEntries(storage) {
+	if (!storage) return [];
+	let raw = null;
+	try {
+		raw = storage.getItem(STORAGE_KEY);
+	} catch {
+		return [];
+	}
+	if (!raw) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "number" && typeof entry[2] === "number");
+	} catch {
+		return [];
+	}
+}
+/**
+* Create a scroll position store backed by the given storage (normally
+* `sessionStorage`). Storage failures (private mode, quota) degrade to an
+* in-memory map for the current page lifetime.
+*/
+function createScrollPositionStore(storage, maxEntries = MAX_SCROLL_ENTRIES) {
+	const positions = /* @__PURE__ */ new Map();
+	for (const [key, x, y] of readEntries(storage)) positions.set(key, {
+		x,
+		y
+	});
+	function persist() {
+		if (!storage) return;
+		const entries = [];
+		for (const [key, position] of positions) entries.push([
+			key,
+			position.x,
+			position.y
+		]);
+		try {
+			storage.setItem(STORAGE_KEY, JSON.stringify(entries));
+		} catch {}
+	}
+	return {
+		get(key) {
+			return positions.get(key) ?? null;
+		},
+		set(key, position) {
+			positions.delete(key);
+			positions.set(key, position);
+			while (positions.size > maxEntries) {
+				const oldest = positions.keys().next();
+				if (oldest.done) break;
+				positions.delete(oldest.value);
+			}
+			persist();
+		}
+	};
+}
+function getSessionScrollStorage() {
+	if (typeof window === "undefined") return null;
+	try {
+		return window.sessionStorage ?? null;
+	} catch {
+		return null;
+	}
+}
+function generateScrollKey() {
+	return Math.random().toString(36).slice(2, 10);
+}
+/** Read the pracht scroll key from a `history.state` value, if present. */
+function readScrollKeyFromHistoryState(state) {
+	if (!state || typeof state !== "object") return null;
+	const key = state[HISTORY_STATE_KEY];
+	return typeof key === "string" ? key : null;
+}
+/** Merge the pracht scroll key into an existing `history.state` value. */
+function withScrollKeyInHistoryState(state, key) {
+	if (state && typeof state === "object" && !Array.isArray(state)) return {
+		...state,
+		[HISTORY_STATE_KEY]: key
+	};
+	return { [HISTORY_STATE_KEY]: key };
+}
+//#endregion
 //#region src/router.ts
 const NavigateContext = createContext(async () => {});
 function useNavigate() {
@@ -232,11 +319,56 @@ async function initClientRouter(options) {
 	let routeStateVersion = 0;
 	let latestNavigationId = 0;
 	let activeNavigationAbort = null;
+	const scrollStore = createScrollPositionStore(getSessionScrollStorage());
+	if ("scrollRestoration" in history) history.scrollRestoration = "manual";
+	let currentScrollKey = readScrollKeyFromHistoryState(history.state) ?? "";
+	const hadExistingScrollKey = currentScrollKey !== "";
+	if (!hadExistingScrollKey) {
+		currentScrollKey = generateScrollKey();
+		try {
+			history.replaceState(withScrollKeyInHistoryState(history.state, currentScrollKey), "", window.location.href);
+		} catch {}
+	}
+	function saveScrollPosition() {
+		scrollStore.set(currentScrollKey, {
+			x: window.scrollX,
+			y: window.scrollY
+		});
+	}
+	window.addEventListener("pagehide", saveScrollPosition);
+	function restoreOrResetScroll(opts, browserUrl) {
+		if (opts?.preserveScroll) return;
+		if (opts?._popstate) {
+			const saved = scrollStore.get(currentScrollKey);
+			window.scrollTo(saved?.x ?? 0, saved?.y ?? 0);
+			return;
+		}
+		const hashIndex = browserUrl.indexOf("#");
+		if (hashIndex !== -1) {
+			let id = browserUrl.slice(hashIndex + 1);
+			try {
+				id = decodeURIComponent(id);
+			} catch {}
+			const hashTarget = id ? document.getElementById(id) : null;
+			if (hashTarget && typeof hashTarget.scrollIntoView === "function") {
+				hashTarget.scrollIntoView();
+				return;
+			}
+		}
+		window.scrollTo(0, 0);
+	}
+	let afterCommitCallback = null;
 	function RouterRoot({ initialState }) {
 		const [routeState, setRouteState] = useState(initialState);
 		updateRouteState = setRouteState;
 		const navigateValue = useMemo(() => navigate, []);
 		const { Shell, Component, componentProps, data, params, routeId, url, version } = routeState;
+		useLayoutEffect(() => {
+			if (!afterCommitCallback) return;
+			const callback = afterCommitCallback;
+			afterCommitCallback = null;
+			callback();
+		}, [version]);
 		const componentTree = Shell ? h(Shell, null, h(Component, componentProps)) : h(Component, componentProps);
 		return h(NavigateContext.Provider, { value: navigateValue }, h(PrachtRuntimeProvider, {
 			data,
@@ -337,69 +469,86 @@ async function initClientRouter(options) {
 			window.location.href = target.browserUrl;
 			return;
 		}
-		let statePromise;
-		if (routeNeedsServerFetch(match.route)) statePromise = getCachedRouteState(target.requestUrl) ?? fetchPrachtRouteState(target.requestUrl, { signal: abortController.signal });
-		else statePromise = Promise.resolve({
-			type: "data",
-			data: void 0
-		});
-		const routeModPromise = startRouteImport(match);
-		const shellModPromise = startShellImport(match);
-		let state = {
-			data: void 0,
-			error: null
-		};
+		const navigationToken = beginLoadingNavigation(createNavigationLocation(target.browserUrl));
 		try {
-			const result = await statePromise;
-			if (navigationId !== latestNavigationId) return;
-			if (result.type === "redirect") {
-				if (result.location) {
-					const redirect = resolveRedirectTarget(result.location);
-					if (redirect.unsafe) {
-						console.error(`[pracht] refused to navigate to unsafe URL: ${result.location}`);
-						return;
-					}
-					if (redirect.externalUrl) {
-						window.location.href = redirect.externalUrl;
-						return;
-					}
-					if (redirect.isCurrentLocation) return;
-					if (redirect.documentUrl) {
-						window.location.href = redirect.documentUrl;
-						return;
-					}
-					if (redirect.internalPath) {
-						await navigate(redirect.internalPath, opts);
+			let statePromise;
+			if (routeNeedsServerFetch(match.route)) statePromise = getCachedRouteState(target.requestUrl) ?? fetchPrachtRouteState(target.requestUrl, { signal: abortController.signal });
+			else statePromise = Promise.resolve({
+				type: "data",
+				data: void 0
+			});
+			const routeModPromise = startRouteImport(match);
+			const shellModPromise = startShellImport(match);
+			let state = {
+				data: void 0,
+				error: null
+			};
+			try {
+				const result = await statePromise;
+				if (navigationId !== latestNavigationId) return;
+				if (result.type === "redirect") {
+					if (result.location) {
+						const redirect = resolveRedirectTarget(result.location);
+						if (redirect.unsafe) {
+							console.error(`[pracht] refused to navigate to unsafe URL: ${result.location}`);
+							return;
+						}
+						if (redirect.externalUrl) {
+							window.location.href = redirect.externalUrl;
+							return;
+						}
+						if (redirect.isCurrentLocation) return;
+						if (redirect.documentUrl) {
+							window.location.href = redirect.documentUrl;
+							return;
+						}
+						if (redirect.internalPath) {
+							await navigate(redirect.internalPath, opts);
+							return;
+						}
+						window.location.href = target.browserUrl;
 						return;
 					}
 					window.location.href = target.browserUrl;
 					return;
 				}
+				if (result.type === "error") state = {
+					data: void 0,
+					error: result.error
+				};
+				else state = {
+					data: result.data,
+					error: null
+				};
+			} catch {
+				if (abortController.signal.aborted || navigationId !== latestNavigationId) return;
 				window.location.href = target.browserUrl;
 				return;
 			}
-			if (result.type === "error") state = {
-				data: void 0,
-				error: result.error
-			};
-			else state = {
-				data: result.data,
-				error: null
+			if (navigationId !== latestNavigationId) return;
+			if (!opts?._popstate) {
+				saveScrollPosition();
+				if (opts?.replace) history.replaceState(withScrollKeyInHistoryState(history.state, currentScrollKey), "", target.browserUrl);
+				else {
+					const nextScrollKey = generateScrollKey();
+					history.pushState(withScrollKeyInHistoryState(null, nextScrollKey), "", target.browserUrl);
+					currentScrollKey = nextScrollKey;
+				}
+			}
+			const routeState = await resolveRouteState(match, state, target.requestUrl, routeModPromise, shellModPromise);
+			if (navigationId !== latestNavigationId) return;
+			if (!routeState) {
+				window.location.href = target.browserUrl;
+				return;
+			}
+			const commit = () => {
+				afterCommitCallback = () => restoreOrResetScroll(opts, target.browserUrl);
+				applyRouteState(routeState);
 			};
-		} catch {
-			if (abortController.signal.aborted || navigationId !== latestNavigationId) return;
-			window.location.href = target.browserUrl;
-			return;
+			await commitWithOptionalViewTransition(commit, opts?.viewTransition ?? app.viewTransitions === true);
+		} finally {
+			settleNavigation(navigationToken);
 		}
-		if (navigationId !== latestNavigationId) return;
-		if (!opts?._popstate) if (opts?.replace) history.replaceState(null, "", target.browserUrl);
-		else history.pushState(null, "", target.browserUrl);
-		const routeState = await resolveRouteState(match, state, target.requestUrl, routeModPromise, shellModPromise);
-		if (navigationId !== latestNavigationId) return;
-		if (routeState) {
-			applyRouteState(routeState);
-			window.scrollTo(0, 0);
-		} else window.location.href = target.browserUrl;
 	}
 	const initialTarget = resolveBrowserRouteTarget(options.initialState.url);
 	const initialRequestUrl = initialTarget?.requestUrl ?? options.initialState.url;
@@ -468,21 +617,65 @@ async function initClientRouter(options) {
 		}
 		if (url.origin !== window.location.origin) return;
 		e.preventDefault();
-		navigate(url.pathname + url.search + url.hash);
+		const navOptions = {};
+		if (anchor.hasAttribute("data-pracht-preserve-scroll")) navOptions.preserveScroll = true;
+		if (anchor.hasAttribute("data-pracht-view-transition")) navOptions.viewTransition = true;
+		navigate(url.pathname + url.search + url.hash, navOptions);
 	});
 	window.addEventListener("popstate", () => {
+		saveScrollPosition();
+		let nextScrollKey = readScrollKeyFromHistoryState(history.state);
+		if (!nextScrollKey) {
+			nextScrollKey = generateScrollKey();
+			try {
+				history.replaceState(withScrollKeyInHistoryState(history.state, nextScrollKey), "", window.location.href);
+			} catch {}
+		}
+		currentScrollKey = nextScrollKey;
 		navigate(window.location.pathname + window.location.search + window.location.hash, { _popstate: true });
 	});
 	window.__PRACHT_NAVIGATE__ = navigate;
 	window.__PRACHT_ROUTER_READY__ = true;
+	document.documentElement.setAttribute("data-pracht-hydrated", "true");
+	if (hadExistingScrollKey) {
+		const savedPosition = scrollStore.get(currentScrollKey);
+		if (savedPosition) window.scrollTo(savedPosition.x, savedPosition.y);
+	}
 	const warmModules = (match) => {
 		startRouteImport(match);
 		startShellImport(match);
 	};
-	import("./prefetch-D9amIQtw.mjs").then(({ setupPrefetching }) => {
+	registerPrefetchTarget(app, warmModules);
+	import("./prefetch-COYeuvQK.mjs").then(({ setupPrefetching }) => {
 		setupPrefetching(app, warmModules);
 	});
 }
+/**
+* Commit a navigation's DOM update, optionally wrapped in
+* `document.startViewTransition()`. Falls back to a plain commit when view
+* transitions are disabled or unsupported. Resolves once the DOM update has
+* been applied (not when the transition animation finishes).
+*/
+async function commitWithOptionalViewTransition(commit, useViewTransition) {
+	const doc = document;
+	if (!useViewTransition || typeof doc.startViewTransition !== "function") {
+		commit();
+		return;
+	}
+	let committed = false;
+	let transition;
+	try {
+		transition = doc.startViewTransition(async () => {
+			committed = true;
+			commit();
+			await new Promise((resolve) => setTimeout(resolve, 0));
+		});
+	} catch {}
+	try {
+		await transition?.updateCallbackDone;
+	} catch {}
+	if (!committed) commit();
+}
 function resolveBrowserRouteTarget(to) {
 	if (typeof window === "undefined") return null;
 	try {