@absolutejs/absolute 0.20.0-beta.169 → 0.20.0-beta.170

package/dist/svelte/router/Link.svelte

@@ -1,8 +1,13 @@
 <script lang="ts">
 	import { onDestroy, onMount, type Snippet } from 'svelte';
 	import type { LinkPrefetchMode } from '../../types/svelteRouter';
-	import { goto } from './goto';
 	import {
+		belongsToDocumentNavigation,
+		navigate,
+		preloadRoute
+	} from './navigation';
+	import {
+		canPrefetch,
 		observeViewport,
 		prefetch,
 		resolveDefaultPrefetchMode,
@@ -26,7 +31,8 @@
 		prerender?: boolean;
 		/** Don't reset focus to body on navigate. */
 		keepFocus?: boolean;
-		/** Don't scroll to top on navigate. */
+		/** Leave the scroll position alone on navigate (no scroll to the
+		 *  top or to the `#hash` target). */
 		noScroll?: boolean;
 		/** Forwarded to the underlying `<a>` element. */
 		class?: string;
@@ -77,19 +83,42 @@
 		if (target && target !== '_self') return;
 		if (rest['download'] !== undefined) return;
 		if (isExternal(to)) return;
+		// No <Router> here has a route for `to` and cross-framework
+		// navigation is on: another page owns the URL, so the click goes to
+		// the browser, where the navigation layer swaps that page in.
+		if (belongsToDocumentNavigation(to)) return;
 
 		event.preventDefault();
-		void goto(to, {
-			keepFocus,
-			noScroll,
-			replaceState
+		navigate(
+			to,
+			{
+				keepFocus,
+				noScroll,
+				replaceState
+			},
+			'link'
+		).catch((navigationError: unknown) => {
+			console.error(
+				'[absolute] <Link> navigation failed:',
+				navigationError
+			);
 		});
 	};
 
+	// A lazy route's component chunk is part of what a prefetch warms, on
+	// the same triggers (hover, viewport, pointerdown) and under the same
+	// data-saver / opt-out rules as the document prefetch.
+	const preloadLazyRoute = () => {
+		if (canPrefetch()) preloadRoute(to);
+	};
+
 	const handlePointerEnter = () => {
 		if (resolvedMode() === 'none' || isExternal(to)) return;
 		hoverHandle?.cancel();
-		hoverHandle = scheduleHoverPrefetch(to, { prerender });
+		hoverHandle = scheduleHoverPrefetch(to, {
+			onPrefetch: preloadLazyRoute,
+			prerender
+		});
 	};
 
 	const handlePointerLeave = () => {
@@ -102,6 +131,7 @@
 		hoverHandle?.cancel();
 		hoverHandle = null;
 		prefetch(to, { kind: 'route' });
+		preloadLazyRoute();
 		if (prerender) speculate(to);
 	};
 
@@ -109,7 +139,9 @@
 		if (resolvedMode() !== 'viewport' || !anchor) return;
 		if (isExternal(to)) return;
 
-		unobserveViewport = observeViewport(anchor, to);
+		unobserveViewport = observeViewport(anchor, to, {
+			onVisible: preloadLazyRoute
+		});
 	});
 
 	onDestroy(() => {

package/dist/svelte/router/Route.svelte

@@ -1,17 +1,52 @@
 <script lang="ts" generics="Path extends string">
 	import { getContext, onDestroy, type Snippet } from 'svelte';
-	import type { ExtractRouteParams } from '../../types/svelteRouter';
+	import type {
+		ExtractRouteParams,
+		LazyRouteLoader,
+		RouteGuard,
+		SvelteRouterSsrState
+	} from '../../types/svelteRouter';
 	import type { RouterRegistry } from './Router.svelte';
+	import { forgetLazy, lazyCacheKey, loadLazy, peekLazy } from './lazy';
+	import type { LazyComponent } from './lazyModule';
 	import { compilePattern, joinBasepath } from './matchPath';
 
 	const ROUTER_CONTEXT_KEY = Symbol.for('absolutejs.svelte-router');
+	const ROUTER_SSR_KEY = Symbol.for('absolutejs.svelte-router.ssr');
 
 	type RouteProps = {
 		path: Path;
-		content: Snippet<[ExtractRouteParams<Path>]>;
+		/** Eager route: the snippet to render while the route is active. */
+		content?: Snippet<[ExtractRouteParams<Path>]>;
+		/** Lazy route: loads the component the first time the route is
+		 *  needed — `() => import('./Page.svelte')`. The build splits it
+		 *  into its own chunk; the server awaits it so the HTML is complete
+		 *  and hydration matches. The component receives the route params
+		 *  (and `props`) as props. */
+		loader?: LazyRouteLoader;
+		/** Extra props for a lazy route's component. */
+		props?: Record<string, unknown>;
+		/** Rendered while a lazy route's component loads in the browser. */
+		pending?: Snippet;
+		/** Rendered when a lazy route's loader rejects. `retry` calls the
+		 *  loader again. */
+		error?: Snippet<[unknown, () => void]>;
+		/** Runs before navigating onto this route, after the router's
+		 *  guards. Runs during the server render too (a redirect becomes a
+		 *  302). Return `false` to cancel, a URL or `redirect(...)` to
+		 *  redirect, nothing to allow. */
+		guard?: RouteGuard;
 	};
 
-	let { path, content }: RouteProps = $props();
+	let {
+		path,
+		content,
+		loader,
+		props: extraProps,
+		pending,
+		error,
+		guard
+	}: RouteProps = $props();
 
 	const registry = getContext<RouterRegistry | undefined>(ROUTER_CONTEXT_KEY);
 	if (!registry) {
@@ -20,25 +55,34 @@
 				'Wrap your routes in `<Router url={...}>` (server) or `<Router>` (client).'
 		);
 	}
+	const ssr = getContext<SvelteRouterSsrState | undefined>(ROUTER_SSR_KEY);
 
 	const id = registry.nextRouteId();
 	const registrationOrder = Number(id.slice(1));
+	const fullPath = $derived(joinBasepath(registry.basepath, path));
 
-	// Register synchronously at script-body time so SSR (which doesn't
-	// run $effect) sees the registration before the template runs.
-	registry.register(id, {
+	const createEntry = () => ({
+		fullPath: joinBasepath(registry.basepath, path),
+		getGuard: () => guard,
+		getLoader: () => loader,
 		pattern: compilePattern(joinBasepath(registry.basepath, path)),
 		registrationOrder
 	});
 
+	// Register synchronously at script-body time so SSR (which doesn't
+	// run $effect) sees the registration before the template runs.
+	registry.register(id, createEntry());
+
 	$effect(() => {
-		registry.register(id, {
-			pattern: compilePattern(joinBasepath(registry.basepath, path)),
-			registrationOrder
-		});
+		registry.register(id, createEntry());
 	});
 
-	onDestroy(() => registry.deregister(id));
+	// The server render runs onDestroy as soon as the HTML is produced, but
+	// the router's guards run after that (between render passes) and need
+	// the full route table — so only the browser deregisters.
+	onDestroy(() => {
+		if (typeof window !== 'undefined') registry.deregister(id);
+	});
 
 	// The Router computes the active match across all registered Routes
 	// (specificity-ranked). Each Route checks if it's the winner and
@@ -47,8 +91,109 @@
 	// that section instead of getting hoisted to the Router's root.
 	const match = $derived(registry.getActiveMatch());
 	const isActive = $derived(match?.id === id);
+
+	// ---- Lazy routes ---------------------------------------------------
+	//
+	// Browser: the component comes from the lazy cache — loaded on an
+	// earlier visit, by a <Link> prefetch, or (first hydration) by the
+	// hydration entry, which loads the modules the server rendered before
+	// it hydrates. Otherwise the effect below loads it while `pending`
+	// renders.
+	//
+	// Server: the first render pass registers the load with the page
+	// handler, which awaits it and renders again with the component
+	// resolved, so the HTML holds the real component.
+	const cacheKey = $derived(loader ? lazyCacheKey(fullPath, loader) : '');
+	// Read synchronously at creation so the first (hydrating) render
+	// already has the component when it is available.
+	const peekInitialComponent = () =>
+		!ssr && loader
+			? peekLazy(lazyCacheKey(fullPath, loader), fullPath)
+			: undefined;
+	let loadedComponent = $state<LazyComponent | undefined>(
+		peekInitialComponent()
+	);
+	let loadFailure = $state<{ error: unknown } | undefined>(undefined);
+
+	const serverLazy = (active: boolean) => {
+		if (!ssr || !loader || !active) return undefined;
+		const resolved = ssr.resolved.get(fullPath);
+		if (!resolved) ssr.load(fullPath, loader);
+		// No `error` snippet: fail the render like any other SSR error.
+		if (resolved && 'error' in resolved && !error) throw resolved.error;
+
+		return resolved;
+	};
+
+	const serverResolved = $derived(serverLazy(isActive));
+	const Loaded = $derived(
+		ssr
+			? serverResolved && 'component' in serverResolved
+				? serverResolved.component
+				: undefined
+			: loadedComponent
+	);
+	const failure = $derived(
+		ssr
+			? serverResolved && 'error' in serverResolved
+				? { error: serverResolved.error }
+				: undefined
+			: loadFailure
+	);
+
+	const reportLoadFailure = (reason: unknown) => {
+		loadFailure = { error: reason };
+		// No `error` snippet: surface it like any uncaught error (the dev
+		// overlay shows it) instead of failing silently.
+		if (!error) {
+			queueMicrotask(() => {
+				throw reason;
+			});
+		}
+	};
+
+	$effect(() => {
+		if (!loader || !isActive || loadFailure) return;
+		const key = cacheKey;
+		const cached = peekLazy(key, fullPath);
+		if (cached) {
+			if (loadedComponent !== cached) loadedComponent = cached;
+
+			return;
+		}
+		if (loadedComponent) loadedComponent = undefined;
+		let live = true;
+		loadLazy(key, loader).then(
+			(component) => {
+				if (live) loadedComponent = component;
+			},
+			(reason: unknown) => {
+				if (live) reportLoadFailure(reason);
+			}
+		);
+
+		return () => {
+			live = false;
+		};
+	});
+
+	const retry = () => {
+		forgetLazy(cacheKey);
+		loadFailure = undefined;
+		loadedComponent = undefined;
+	};
 </script>
 
 {#if isActive && match}
-	{@render content(match.params as ExtractRouteParams<Path>)}
+	{#if loader}
+		{#if Loaded}
+			<Loaded {...extraProps ?? {}} {...match.params} />
+		{:else if failure}
+			{@render error?.(failure.error, retry)}
+		{:else if pending}
+			{@render pending()}
+		{/if}
+	{:else if content}
+		{@render content(match.params as ExtractRouteParams<Path>)}
+	{/if}
 {/if}

package/dist/svelte/router/Route.svelte.d.ts

@@ -1,13 +1,47 @@
 import { SvelteComponent, type Snippet } from 'svelte';
-import type { ExtractRouteParams } from '../../types/svelteRouter';
+import type {
+	ExtractRouteParams,
+	LazyRouteLoader,
+	RouteGuard
+} from '../../types/svelteRouter';
 
-type RouteProps<Path extends string> = {
+type RouteBaseProps<Path extends string> = {
 	path: Path;
+	/** Runs before navigating onto this route, after the router's guards
+	 *  (and during the server render, where a redirect becomes a 302). */
+	guard?: RouteGuard;
+};
+
+/** Eager route: render a snippet while the route is active. */
+type EagerRouteProps<Path extends string> = RouteBaseProps<Path> & {
 	content: Snippet<[ExtractRouteParams<Path>]>;
+	loader?: never;
+	props?: never;
+	pending?: never;
+	error?: never;
 };
 
-class Route<Path extends string = string> extends SvelteComponent<
-	RouteProps<Path>
-> {}
+/** Lazy route: load the component on first use —
+ *  `loader={() => import('./Page.svelte')}`. It receives the route params
+ *  (plus `props`) as props. */
+type LazyRouteProps<
+	Path extends string,
+	Props extends Record<string, unknown>
+> = RouteBaseProps<Path> & {
+	content?: never;
+	loader: LazyRouteLoader<Props>;
+	props?: Omit<Props, keyof ExtractRouteParams<Path>>;
+	pending?: Snippet;
+	error?: Snippet<[unknown, () => void]>;
+};
+
+type RouteProps<Path extends string, Props extends Record<string, unknown>> =
+	| EagerRouteProps<Path>
+	| LazyRouteProps<Path, Props>;
+
+class Route<
+	Path extends string = string,
+	Props extends Record<string, unknown> = ExtractRouteParams<Path>
+> extends SvelteComponent<RouteProps<Path, Props>> {}
 
 export { Route as default };

package/dist/svelte/router/Router.svelte

@@ -2,8 +2,17 @@
 	type RouteEntry = {
 		// reactive — read by the winner-resolver
 		pattern: ReturnType<typeof import('./matchPath').compilePattern>;
+		// basepath-joined path pattern, the lazy-route cache key
+		fullPath: string;
 		// stable — assigned at registration time, used as tiebreaker
 		registrationOrder: number;
+		// read on demand so a changed prop is always seen
+		getGuard: () =>
+			| import('../../types/svelteRouter').RouteGuard
+			| undefined;
+		getLoader: () =>
+			| import('../../types/svelteRouter').LazyRouteLoader
+			| undefined;
 	};
 
 	type ActiveMatch = {
@@ -27,13 +36,27 @@
 
 <script lang="ts">
 	import { getContext, onMount, setContext, type Snippet } from 'svelte';
-	import type { RouterMode } from '../../types/svelteRouter';
-	import { setRouterMode } from './goto';
-	import { hashPathnameOf } from './hashMode';
+	import type {
+		RouteGuard,
+		RouterMode,
+		SvelteRouterSsrState
+	} from '../../types/svelteRouter';
+	import { type GuardEntry, runGuardChain } from './guards';
+	import { buildHashHref, hashPathnameOf } from './hashMode';
+	import { lazyCacheKey, loadLazy } from './lazy';
 	import { joinBasepath, matchPattern } from './matchPath';
-	import { page, seedPage, setPage } from './page.js';
+	import {
+		enterInitialRoute,
+		handleTraversal,
+		registerRouter,
+		restoreInitialScroll,
+		setRouterMode
+	} from './navigation';
+	import { page, seedPage } from './page.js';
+	import { activateScrollRestoration, stampInitialEntry } from './scroll';
 
 	const ROUTER_CONTEXT_KEY = Symbol.for('absolutejs.svelte-router');
+	const ROUTER_SSR_KEY = Symbol.for('absolutejs.svelte-router.ssr');
 
 	type RouterProps = {
 		/** SSR URL passthrough. On the server, the page handler forwards
@@ -46,6 +69,12 @@
 		/** `'history'` (default, clean URLs) or `'hash'` (`/#/path`,
 		 *  for static deploys). */
 		mode?: RouterMode;
+		/** Runs before every navigation onto this router's routes (the
+		 *  outermost router: every navigation), before the matched
+		 *  `<Route guard>`. Runs during the server render too, where a
+		 *  redirect becomes a 302. Return `false` to cancel, a URL or
+		 *  `redirect(...)` to redirect, nothing to allow. */
+		guard?: RouteGuard;
 		children?: Snippet;
 	};
 
@@ -53,10 +82,12 @@
 		url,
 		basepath = '',
 		mode = 'history',
+		guard,
 		children
 	}: RouterProps = $props();
 
 	const parent = getContext<RouterRegistry | undefined>(ROUTER_CONTEXT_KEY);
+	const ssr = getContext<SvelteRouterSsrState | undefined>(ROUTER_SSR_KEY);
 	const stackedBasepath = parent
 		? joinBasepath(parent.basepath, basepath)
 		: basepath === ''
@@ -77,14 +108,14 @@
 	const routes = $state(new Map<string, RouteEntry>());
 	let routeCounter = 0;
 
-	const computeWinner = (): ActiveMatch | null => {
+	const computeWinnerFor = (pathname: string): ActiveMatch | null => {
 		let bestId: string | null = null;
 		let bestParams: Record<string, string | undefined> | null = null;
 		let bestScore = -Infinity;
 		let bestOrder = Infinity;
 
 		for (const [id, entry] of routes) {
-			const match = matchPattern(entry.pattern, page.url.pathname);
+			const match = matchPattern(entry.pattern, pathname);
 			if (!match.matched) continue;
 
 			if (
@@ -118,7 +149,7 @@
 		deregister: (id) => {
 			routes.delete(id);
 		},
-		getActiveMatch: () => computeWinner(),
+		getActiveMatch: () => computeWinnerFor(page.url.pathname),
 		mode: stackedMode,
 		nextRouteId: () => `r${routeCounter++}`,
 		register: (id, entry) => {
@@ -128,6 +159,39 @@
 
 	setContext<RouterRegistry>(ROUTER_CONTEXT_KEY, registry);
 
+	// Guards for a navigation to `target`: this router's own guard (the
+	// outermost one always; a nested one only when one of its routes
+	// matches), then the matched route's guard.
+	const guardsFor = (target: URL) => {
+		const winner = computeWinnerFor(target.pathname);
+		const entries: GuardEntry[] = [];
+		const routerGuard = guard;
+		if (routerGuard && (isOutermost || winner)) {
+			entries.push({ guard: routerGuard, params: winner?.params ?? {} });
+		}
+		const routeGuard = winner
+			? routes.get(winner.id)?.getGuard()
+			: undefined;
+		if (winner && routeGuard) {
+			entries.push({ guard: routeGuard, params: winner.params });
+		}
+
+		return entries;
+	};
+
+	const matches = (target: URL) => computeWinnerFor(target.pathname) !== null;
+
+	const preload = (target: URL) => {
+		const winner = computeWinnerFor(target.pathname);
+		const entry = winner ? routes.get(winner.id) : undefined;
+		const loader = entry?.getLoader();
+		if (!entry || !loader) return;
+		loadLazy(lazyCacheKey(entry.fullPath, loader), loader).catch(() => {
+			// A failed prefetch is retried (and reported) by the Route
+			// itself if the user actually navigates there.
+		});
+	};
+
 	if (isOutermost) {
 		setRouterMode(stackedMode);
 
@@ -145,31 +209,80 @@
 		seedPage(initial);
 	}
 
+	// Server render: once this pass has registered every Route, run this
+	// router's guards for the request URL. The page handler awaits them
+	// before rendering again; a redirect becomes a 302. The URL is captured
+	// now — `page` is shared module state and other requests may render
+	// before the guards run.
+	if (ssr) {
+		const renderUrl = new URL(page.url.href);
+		const requestUrl = new URL(url ?? '/', 'http://localhost/');
+		const guardKey = `${stackedBasepath}\u0000${renderUrl.href}`;
+		ssr.afterRender(async () => {
+			if (ssr.outcome() !== undefined) return;
+			if (ssr.settledGuards.has(guardKey)) return;
+			ssr.settledGuards.add(guardKey);
+			const decision = await runGuardChain(guardsFor(renderUrl), {
+				from: null,
+				request: ssr.request,
+				to: renderUrl,
+				type: 'enter'
+			});
+			if (decision.kind === 'cancel') ssr.setOutcome({ kind: 'cancel' });
+			if (decision.kind !== 'redirect') return;
+			const target = new URL(decision.location, renderUrl);
+			const location =
+				stackedMode === 'hash'
+					? `${requestUrl.pathname}${requestUrl.search}${buildHashHref(target.pathname + target.search)}`
+					: target.origin === renderUrl.origin
+						? `${target.pathname}${target.search}${target.hash}`
+						: target.href;
+			ssr.setOutcome({ kind: 'redirect', location });
+		});
+	}
+
 	onMount(() => {
-		if (!isOutermost) return;
+		const unregister = registerRouter({ guardsFor, matches, preload });
+		if (!isOutermost) return unregister;
 
-		const onPopState = (event: PopStateEvent) => {
+		const initialEntry = stampInitialEntry();
+		const deactivateScroll = activateScrollRestoration();
+		const navigationEntry = performance.getEntriesByType('navigation')[0];
+		const navigationKind =
+			navigationEntry && 'type' in navigationEntry
+				? navigationEntry.type
+				: undefined;
+		if (
+			initialEntry.scroll &&
+			(navigationKind === 'reload' || navigationKind === 'back_forward')
+		) {
+			void restoreInitialScroll(initialEntry.scroll);
+		}
+		if (stackedMode === 'hash') void enterInitialRoute(page.url);
+
+		const routableUrl = () => {
 			const next = new URL(window.location.href);
-			const routable =
-				stackedMode === 'hash' ? hashPathnameOf(next) : next.pathname;
 			const synthetic = new URL(next.href);
-			synthetic.pathname = routable;
-			setPage({
-				params: {},
-				state: event.state ?? null,
-				url: synthetic
-			});
+			if (stackedMode === 'hash')
+				synthetic.pathname = hashPathnameOf(next);
+
+			return synthetic;
 		};
 
+		let lastTraversalHref = '';
+		const onPopState = (event: PopStateEvent) => {
+			lastTraversalHref = window.location.href;
+			void handleTraversal(event.state, routableUrl());
+		};
+
+		// Browsers fire `popstate` for hash changes too; `hashchange` only
+		// catches the rare engine that doesn't, so skip URLs already handled.
 		const onHashChange = () => {
-			const next = new URL(window.location.href);
-			const synthetic = new URL(next.href);
-			synthetic.pathname = hashPathnameOf(next);
-			setPage({
-				params: {},
-				state: window.history.state ?? null,
-				url: synthetic
-			});
+			if (window.location.href === lastTraversalHref) return;
+			const next = routableUrl();
+			if (next.href === page.url.href) return;
+			lastTraversalHref = window.location.href;
+			void handleTraversal(window.history.state, next);
 		};
 
 		window.addEventListener('popstate', onPopState);
@@ -178,6 +291,8 @@
 		}
 
 		return () => {
+			unregister();
+			deactivateScroll();
 			window.removeEventListener('popstate', onPopState);
 			if (stackedMode === 'hash') {
 				window.removeEventListener('hashchange', onHashChange);

package/dist/svelte/router/Router.svelte.d.ts

@@ -1,10 +1,14 @@
 import { SvelteComponent, type Snippet } from 'svelte';
-import type { RouterMode } from '../../types/svelteRouter';
+import type { RouteGuard, RouterMode } from '../../types/svelteRouter';
 
 type RouterProps = {
 	url?: string;
 	basepath?: string;
 	mode?: RouterMode;
+	/** Runs before every navigation onto this router's routes (the
+	 *  outermost router: every navigation), and during the server render,
+	 *  where a redirect becomes a 302. */
+	guard?: RouteGuard;
 	children?: Snippet;
 };
 

package/dist/svelte/router/browser.ts

@@ -2,13 +2,23 @@
 // their .svelte path; this entry exposes only the runtime API.
 
 export { goto } from './goto';
+export { NavigationRedirect, redirect } from './guards';
+export { beforeNavigate, preloadRoute } from './navigation';
 export { page } from './page.js';
 export { pushState, replaceState } from './pushState';
 
 export type {
 	ExtractRouteParams,
 	GotoOptions,
+	LazyRouteLoader,
+	LazyRouteModule,
 	LinkPrefetchMode,
+	NavigationContext,
+	NavigationOutcome,
+	NavigationRedirectTarget,
+	NavigationType,
 	PageState,
+	RouteGuard,
+	RouteGuardResult,
 	RouterMode
 } from '../../types/svelteRouter';