@buzola/router 0.0.4 → 0.0.6

package/src/__tests__/matcher.test.ts

@@ -116,6 +116,35 @@ describe('matchRoutes', () => {
 		expect(matches).toBeNull()
 	})
 
+	it('matches routes with trailing slash', () => {
+		const tree = createTestTree([
+			{ path: '/about', component: dummyComponent },
+		])
+
+		const matches = matchRoutes(tree, new URL('http://localhost/about/'))
+		expect(matches).not.toBeNull()
+		expect(matches).toHaveLength(1)
+		expect(matches![0].node.fullPath).toBe('/about')
+	})
+
+	it('matches nested routes with trailing slash', () => {
+		const tree = createTestTree([
+			{
+				path: '/users',
+				component: dummyComponent,
+				isLayout: true,
+				children: [
+					{ path: '/:userId', component: dummyComponent },
+				],
+			},
+		])
+
+		const matches = matchRoutes(tree, new URL('http://localhost/users/42/'))
+		expect(matches).not.toBeNull()
+		expect(matches).toHaveLength(2)
+		expect(matches![1].params).toEqual({ userId: '42' })
+	})
+
 	it('does not match partial paths', () => {
 		const tree = createTestTree([
 			{ path: '/about', component: dummyComponent },

package/src/__tests__/router.test.ts

@@ -212,3 +212,61 @@ describe('Router.resolveParams', () => {
 		expect(result).toEqual({})
 	})
 })
+
+describe('Router.preload', () => {
+	it('calls preload on matching route nodes', () => {
+		const preloadFn = mock(() => {})
+		const routes = buildRouteTree([
+			{ path: '/', component: dummyComponent, isIndex: true },
+			{ path: '/users/:userId', component: dummyComponent, preload: preloadFn },
+		])
+		const adapter = createMemoryNavigationAdapter({ initialURL: 'http://localhost/' })
+		const router = new Router({
+			routes,
+			adapter,
+			pageRegistry: { 'users/detail': '/users/:userId' },
+		})
+
+		router.preload('users/detail', { userId: '42' })
+		expect(preloadFn).toHaveBeenCalledTimes(1)
+	})
+
+	it('calls preload on all matched nodes (layout + page)', () => {
+		const layoutPreload = mock(() => {})
+		const pagePreload = mock(() => {})
+		const routes = buildRouteTree([{
+			path: '/users',
+			component: dummyComponent,
+			preload: layoutPreload,
+			isLayout: true,
+			children: [
+				{ path: '/:userId', component: dummyComponent, preload: pagePreload },
+			],
+		}])
+		const adapter = createMemoryNavigationAdapter({ initialURL: 'http://localhost/' })
+		const router = new Router({
+			routes,
+			adapter,
+			pageRegistry: { 'users/detail': '/users/:userId' },
+		})
+
+		router.preload('users/detail', { userId: '1' })
+		expect(layoutPreload).toHaveBeenCalledTimes(1)
+		expect(pagePreload).toHaveBeenCalledTimes(1)
+	})
+
+	it('does not throw for unmatched page', () => {
+		const routes = buildRouteTree([
+			{ path: '/', component: dummyComponent, isIndex: true },
+		])
+		const adapter = createMemoryNavigationAdapter({ initialURL: 'http://localhost/' })
+		const router = new Router({
+			routes,
+			adapter,
+			pageRegistry: { 'about': '/about' },
+		})
+
+		// Should not throw
+		router.preload('about')
+	})
+})

package/src/__tests__/type-safety.test.tsx

@@ -108,6 +108,30 @@ describe('createPage catch type safety', () => {
 		withCatch.loader
 		expect(true).toBe(true)
 	})
+
+	it('.catch() handler receives typed params', () => {
+		const _page = createPage()
+			.params(mockSchema<{ userId: string; tab: string }>())
+			.catch(({ error, params, retry }) => {
+				// params should be typed as { userId: string; tab: string }
+				const _userId: string = params.userId
+				const _tab: string = params.tab
+				return <div>{error.message}</div>
+			})
+			.render(() => null)
+		expect(true).toBe(true)
+	})
+
+	it('.catch() handler has empty params when no schema defined', () => {
+		const _page = createPage()
+			.catch(({ params }) => {
+				// @ts-expect-error — no params defined, accessing unknown key
+				params.anything
+				return null
+			})
+			.render(() => null)
+		expect(true).toBe(true)
+	})
 })
 
 // ─── LinkProps ──────────────────────────────────────────────────────────────

package/src/define/create-page.tsx

@@ -1,6 +1,6 @@
 import type { ReactElement } from 'react'
 import { type ComponentType, use, useCallback, useEffect, useMemo, useReducer, useState } from 'react'
-import type { LoaderCache } from '../engine/loader-cache.js'
+import { PageLoaderState } from '../engine/loader-state.js'
 import { isOptionalSchema, type ParamLiteral, resolveParamLiteral, validateSchema } from '../engine/schema.js'
 import type { EffectivePageParams, RegisteredPage, RouteComponent, StandardSchema } from '../engine/types.js'
 import { extractParamNames } from '../engine/utils.js'
@@ -11,12 +11,15 @@ export interface PageProps<TParams> {
 	params: TParams
 }
 
-export interface CatchContext {
+export interface CatchContext<TParams = Record<string, never>> {
 	error: Error
+	params: TParams
 	retry: () => void
 }
 
-type CatchHandler = React.ReactNode | ((ctx: CatchContext) => React.ReactNode)
+type CatchHandler<TParams = Record<string, never>> =
+	| React.ReactNode
+	| ((ctx: CatchContext<TParams>) => React.ReactNode)
 
 export interface ParamMeta {
 	name: string
@@ -153,50 +156,20 @@ function combineLoaders(loaders: LoaderFn[]): LoaderFn | undefined {
 
 // ─── Component factory ──────────────────────────────────────────────────────
 
-let nextPageId = 0
-
 function createPageComponent<TParams>(
 	schema: StandardSchema<TParams> | undefined,
 	paramsMeta: ParamMeta[],
 	loaderFn: LoaderFn | undefined,
 	routePattern: string | undefined,
 	RenderComponent: ComponentType<any>,
-	catchHandler?: CatchHandler,
+	catchHandler?: CatchHandler<TParams>,
 ): PageDefinition<TParams> {
 	const arrayParams = new Set(paramsMeta.filter(m => m.array).map(m => m.name))
 
-	// Loader promise cache lives in the closure, outside React's render cycle.
-	// This is critical: when use() suspends during the initial render, React
-	// discards all uncommitted hook state (useRef, useState, useMemo).
-	// On retry, hooks reinitialize, and useMemo/useRef would create a new promise,
-	// causing an infinite suspend loop. The closure cache survives this.
-
-	// Active load state (current URL)
-	let activeUrlHref: string | null = null
-	let activeCacheKey: string | null = null
-	let activePromise: Promise<unknown> | null = null
-	let activeResolvedData: unknown
-	let hasResolved = false
-	let pendingBackgroundKey: string | null = null
-
-	// Unique ID for namespacing entries in the global loader cache
-	const pageId = nextPageId++
-
-	function staleCacheKey(urlHref: string): string {
-		return `${pageId}:${urlHref}`
-	}
-
-	function staleCacheGet(cache: LoaderCache, urlHref: string): { hit: true; value: unknown } | { hit: false } {
-		const key = staleCacheKey(urlHref)
-		if (!cache.has(key)) return { hit: false }
-		const value = cache.get(key)
-		cache.delete(key)
-		return { hit: true, value }
-	}
-
-	function staleCacheSet(cache: LoaderCache, urlHref: string, value: unknown): void {
-		cache.set(staleCacheKey(urlHref), value)
-	}
+	// Loader state lives in the closure, outside React's render cycle.
+	// This is critical: when use() suspends, React discards uncommitted hook
+	// state. The PageLoaderState instance survives Suspense retries.
+	const loaderState = loaderFn ? new PageLoaderState() : undefined
 
 	function BuzolaPage(): ReactElement | null {
 		const routeContext = use(RouteContext)
@@ -259,120 +232,51 @@ function createPageComponent<TParams>(
 			return router.onInvalidate(() => setLoaderKey(k => k + 1))
 		}, [router])
 
-		const loaderCache = router?.loaderCache
-
 		let data: unknown
 		let isLoading = false
 		let shouldRedirect = false
 
-		if (loaderFn) {
+		if (loaderFn && loaderState) {
 			const currentUrlHref = routeContext.state.location.href
 			const cacheKey = `${currentUrlHref}:${loaderKey}`
 
-			// URL changed — save old data to stale cache, restore from stale cache if available
-			if (activeUrlHref !== null && activeUrlHref !== currentUrlHref) {
-				if (loaderCache && hasResolved && activeResolvedData !== undefined) {
-					staleCacheSet(loaderCache, activeUrlHref, activeResolvedData)
-				}
-
-				const cached = loaderCache && staleCacheGet(loaderCache, currentUrlHref)
-				if (cached?.hit) {
-					activeResolvedData = cached.value
-					hasResolved = true
-				} else {
-					hasResolved = false
-					activeResolvedData = undefined
-				}
-				pendingBackgroundKey = null
-			} else if (activeUrlHref === null && loaderCache) {
-				// Remount — restore from stale cache
-				const cached = staleCacheGet(loaderCache, currentUrlHref)
-				if (cached.hit) {
-					activeResolvedData = cached.value
-					hasResolved = true
-				}
-			}
-			activeUrlHref = currentUrlHref
-
-			if (activeCacheKey === cacheKey) {
-				// Cache hit — check if background load is pending
-				if (pendingBackgroundKey === cacheKey) {
-					data = activeResolvedData
-					isLoading = true
-				} else {
-					// Either resolved or first-time suspend
-					if (hasResolved) {
-						data = activeResolvedData
+			const instruction = loaderState.resolve({
+				currentUrlHref,
+				cacheKey,
+				load: () => loaderFn({ params, redirect }),
+				loaderCache: router?.loaderCache,
+				onBackgroundSettled: (outcome) => {
+					if (outcome.ok) {
+						if (outcome.result instanceof BuzolaRedirect) {
+							router?.navigateToPage(outcome.result.pageId, outcome.result.params, { replace: true })
+							return
+						}
+						loaderState.commitBackgroundResult(outcome.result)
 					} else {
-						data = use(activePromise!)
-						activeResolvedData = data
-						hasResolved = true
+						loaderState.commitBackgroundError()
 					}
-				}
-			} else if (hasResolved) {
-				// Cache key changed + we have stale data → background reload (SWR)
-				const promise = loaderFn({ params, redirect })
-				activeCacheKey = cacheKey
-				activePromise = promise
-				pendingBackgroundKey = cacheKey
-				data = activeResolvedData
-				isLoading = true
-
-				promise.then(
-					(result) => {
-						// Only apply if this is still the active load
-						if (activeCacheKey === cacheKey) {
-							if (result instanceof BuzolaRedirect) {
-								router?.navigateToPage(result.pageId, result.params, { replace: true })
-								return
-							}
-							activeResolvedData = result
-							pendingBackgroundKey = null
-							forceUpdate()
-						}
-					},
-					(error) => {
-						// Store rejected promise so use() triggers ErrorBoundary
-						if (activeCacheKey === cacheKey) {
-							activePromise = promise
-							hasResolved = false
-							pendingBackgroundKey = null
-							forceUpdate()
-						}
-					},
-				)
+					forceUpdate()
+				},
+			})
+
+			if (instruction.action === 'render') {
+				data = instruction.data
+				isLoading = instruction.isLoading
 			} else {
-				// No stale data — first load, suspend via use()
-				const promise = loaderFn({ params, redirect })
-				activeCacheKey = cacheKey
-				activePromise = promise
-				const result = use(promise)
+				const result = use(instruction.promise)
 				if (result instanceof BuzolaRedirect) {
 					router?.navigateToPage(result.pageId, result.params, { replace: true })
 					shouldRedirect = true
 				} else {
 					data = result
-				}
-				if (!shouldRedirect) {
-					activeResolvedData = data
-					hasResolved = true
+					loaderState.commitResult(data)
 				}
 			}
 		}
 
-		// On unmount, save active data to stale cache and reset active state
+		// On unmount, save active data to stale cache and reset
 		useEffect(() => {
-			return () => {
-				if (loaderCache && hasResolved && activeResolvedData !== undefined && activeUrlHref) {
-					staleCacheSet(loaderCache, activeUrlHref, activeResolvedData)
-				}
-				hasResolved = false
-				activeResolvedData = undefined
-				activeCacheKey = null
-				activePromise = null
-				pendingBackgroundKey = null
-				activeUrlHref = null
-			}
+			return () => loaderState?.dispose(router?.loaderCache)
 		}, [])
 
 		if (shouldRedirect) return null
@@ -386,7 +290,12 @@ function createPageComponent<TParams>(
 		const retry = useCallback(() => setRetryCount(c => c + 1), [])
 		const resetKey = `${routeContext?.state.location.href ?? ''}:${retryCount}`
 		const boundFallback = typeof catchHandler === 'function'
-			? (error: Error) => (catchHandler as (ctx: CatchContext) => React.ReactNode)({ error, retry })
+			? (error: Error) =>
+				(catchHandler as (ctx: CatchContext<TParams>) => React.ReactNode)({
+					error,
+					params: (routeContext?.params ?? {}) as TParams,
+					retry,
+				})
 			: catchHandler
 		return (
 			<ErrorBoundary fallback={boundFallback} resetKey={resetKey}>
@@ -417,11 +326,11 @@ interface WithCatch<TParams, TRenderProps> {
 }
 
 interface WithRoute<TParams, TRenderProps> {
-	catch(handler: CatchHandler): WithCatch<TParams, TRenderProps>
+	catch(handler: CatchHandler<TParams>): WithCatch<TParams, TRenderProps>
 	route<R extends string>(
 		pattern: [ExtractRouteParams<R>] extends [keyof TParams & string] ? R : never,
 	): {
-		catch(handler: CatchHandler): { render(fn: ComponentType<TRenderProps>): PageDefinition<TParams> }
+		catch(handler: CatchHandler<TParams>): { render(fn: ComponentType<TRenderProps>): PageDefinition<TParams> }
 		render(fn: ComponentType<TRenderProps>): PageDefinition<TParams>
 	}
 	render(fn: ComponentType<TRenderProps>): PageDefinition<TParams>
@@ -447,11 +356,11 @@ interface PageBuilder {
 	loader<TData extends Record<string, unknown>>(
 		fn: (ctx: { params: Record<string, never>; redirect: RedirectFn }) => Promise<TData | BuzolaRedirect>,
 	): WithLoaderChain<Record<string, never>, TData>
-	catch(handler: CatchHandler): WithCatch<Record<string, never>, PageProps<Record<string, never>>>
+	catch(handler: CatchHandler<Record<string, never>>): WithCatch<Record<string, never>, PageProps<Record<string, never>>>
 	route<R extends string>(
 		pattern: [ExtractRouteParams<R>] extends [never] ? R : never,
 	): {
-		catch(handler: CatchHandler): { render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition }
+		catch(handler: CatchHandler<Record<string, never>>): { render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition }
 		render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition
 	}
 	render(fn: ComponentType<PageProps<Record<string, never>>>): PageDefinition
@@ -461,7 +370,7 @@ function withCatchAndRender(
 	schema: StandardSchema | undefined,
 	paramsMeta: ParamMeta[],
 	loaders: LoaderFn[],
-	catchHandler: CatchHandler,
+	catchHandler: CatchHandler<any>,
 ) {
 	return {
 		route(pattern: string) {
@@ -486,12 +395,12 @@ function withRouteAndRender(
 		loader(loaderFn: LoaderFn) {
 			return withRouteAndRender(schema, paramsMeta, [...loaders, loaderFn])
 		},
-		catch(handler: CatchHandler) {
+		catch(handler: CatchHandler<any>) {
 			return withCatchAndRender(schema, paramsMeta, loaders, handler)
 		},
 		route(pattern: string) {
 			return {
-				catch(handler: CatchHandler) {
+				catch(handler: CatchHandler<any>) {
 					return {
 						render(fn: ComponentType<any>) {
 							return createPageComponent(schema, paramsMeta, combineLoaders(loaders), pattern, fn, handler)

package/src/engine/loader-state.ts

@@ -0,0 +1,178 @@
+import type { LoaderCache } from './loader-cache.js'
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type LoaderInstruction =
+	| { action: 'render'; data: unknown; isLoading: boolean }
+	| { action: 'suspend'; promise: Promise<unknown> }
+
+export interface LoaderResolveContext {
+	/** Current URL href — used for stale cache keying */
+	currentUrlHref: string
+	/** Cache key that changes on URL change or invalidation */
+	cacheKey: string
+	/** Factory that starts the actual data fetch */
+	load: () => Promise<unknown>
+	/** Global loader cache for cross-navigation stale data */
+	loaderCache: LoaderCache | undefined
+	/**
+	 * Called when a background (SWR) fetch settles.
+	 * Caller is responsible for calling commitBackgroundResult/commitBackgroundError
+	 * and triggering a React re-render.
+	 */
+	onBackgroundSettled: (outcome: { ok: true; result: unknown } | { ok: false }) => void
+}
+
+// ─── State machine ──────────────────────────────────────────────────────────
+
+let nextId = 0
+
+/**
+ * Manages loader data lifecycle outside of React's render cycle.
+ *
+ * This state survives React Suspense retries — when use() suspends, React
+ * discards uncommitted hook state (useRef, useState, useMemo). Closure/instance
+ * state is preserved, preventing infinite suspend loops from promise recreation.
+ *
+ * Supports stale-while-revalidate: when the cache key changes but stale data
+ * exists, returns stale data immediately and starts a background fetch.
+ */
+export class PageLoaderState {
+	private activeUrlHref: string | null = null
+	private activeCacheKey: string | null = null
+	private activePromise: Promise<unknown> | null = null
+	private activeResolvedData: unknown
+	private hasResolved = false
+	private pendingBackgroundKey: string | null = null
+	private readonly id: number
+
+	constructor() {
+		this.id = nextId++
+	}
+
+	/**
+	 * Determine what the component should do during render.
+	 * Returns either resolved data to render, or a promise to suspend on.
+	 */
+	resolve(ctx: LoaderResolveContext): LoaderInstruction {
+		const { currentUrlHref, cacheKey, load, loaderCache, onBackgroundSettled } = ctx
+
+		this.handleUrlChange(currentUrlHref, loaderCache)
+
+		// ─── Same cache key — return current state ─────
+		if (this.activeCacheKey === cacheKey) {
+			if (this.pendingBackgroundKey === cacheKey) {
+				return { action: 'render', data: this.activeResolvedData, isLoading: true }
+			}
+			if (this.hasResolved) {
+				return { action: 'render', data: this.activeResolvedData, isLoading: false }
+			}
+			return { action: 'suspend', promise: this.activePromise! }
+		}
+
+		// ─── Cache key changed + stale data available → SWR ─────
+		if (this.hasResolved) {
+			const promise = load()
+			this.activeCacheKey = cacheKey
+			this.activePromise = promise
+			this.pendingBackgroundKey = cacheKey
+
+			promise.then(
+				(result) => {
+					if (this.activeCacheKey === cacheKey) {
+						onBackgroundSettled({ ok: true, result })
+					}
+				},
+				() => {
+					if (this.activeCacheKey === cacheKey) {
+						onBackgroundSettled({ ok: false })
+					}
+				},
+			)
+
+			return { action: 'render', data: this.activeResolvedData, isLoading: true }
+		}
+
+		// ─── No stale data → first load, suspend ─────
+		const promise = load()
+		this.activeCacheKey = cacheKey
+		this.activePromise = promise
+		return { action: 'suspend', promise }
+	}
+
+	/** Commit data after use() resolves (suspend case) */
+	commitResult(data: unknown): void {
+		this.activeResolvedData = data
+		this.hasResolved = true
+	}
+
+	/** Commit background SWR success — update data and clear pending flag */
+	commitBackgroundResult(data: unknown): void {
+		this.activeResolvedData = data
+		this.pendingBackgroundKey = null
+	}
+
+	/** Mark background load as failed — next render will suspend with rejected promise */
+	commitBackgroundError(): void {
+		this.hasResolved = false
+		this.pendingBackgroundKey = null
+	}
+
+	/** Save state to stale cache and reset (called on unmount) */
+	dispose(loaderCache: LoaderCache | undefined): void {
+		if (loaderCache && this.hasResolved && this.activeResolvedData !== undefined && this.activeUrlHref) {
+			this.saveToStaleCache(loaderCache, this.activeUrlHref, this.activeResolvedData)
+		}
+		this.activeUrlHref = null
+		this.activeCacheKey = null
+		this.activePromise = null
+		this.activeResolvedData = undefined
+		this.hasResolved = false
+		this.pendingBackgroundKey = null
+	}
+
+	// ─── Private ────────────────────────────────────────────────────────────
+
+	private handleUrlChange(currentUrlHref: string, loaderCache: LoaderCache | undefined): void {
+		if (this.activeUrlHref !== null && this.activeUrlHref !== currentUrlHref) {
+			// URL changed — save old data to stale cache
+			if (loaderCache && this.hasResolved && this.activeResolvedData !== undefined) {
+				this.saveToStaleCache(loaderCache, this.activeUrlHref, this.activeResolvedData)
+			}
+			// Try to restore from stale cache for new URL
+			const cached = loaderCache && this.restoreFromStaleCache(loaderCache, currentUrlHref)
+			if (cached?.hit) {
+				this.activeResolvedData = cached.value
+				this.hasResolved = true
+			} else {
+				this.hasResolved = false
+				this.activeResolvedData = undefined
+			}
+			this.pendingBackgroundKey = null
+		} else if (this.activeUrlHref === null && loaderCache) {
+			// Remount — try to restore from stale cache
+			const cached = this.restoreFromStaleCache(loaderCache, currentUrlHref)
+			if (cached.hit) {
+				this.activeResolvedData = cached.value
+				this.hasResolved = true
+			}
+		}
+		this.activeUrlHref = currentUrlHref
+	}
+
+	private staleCacheKey(urlHref: string): string {
+		return `${this.id}:${urlHref}`
+	}
+
+	private restoreFromStaleCache(cache: LoaderCache, urlHref: string): { hit: true; value: unknown } | { hit: false } {
+		const key = this.staleCacheKey(urlHref)
+		if (!cache.has(key)) return { hit: false }
+		const value = cache.get(key)
+		cache.delete(key)
+		return { hit: true, value }
+	}
+
+	private saveToStaleCache(cache: LoaderCache, urlHref: string, value: unknown): void {
+		cache.set(this.staleCacheKey(urlHref), value)
+	}
+}

package/src/engine/route-tree.ts

@@ -24,6 +24,7 @@ export interface CreateRouteNodeOptions {
 	fullPath: string
 	component?: RouteComponent
 	searchSchema?: StandardSchema
+	preload?: () => void
 	children?: RouteNode[]
 	parent?: RouteNode
 	isLayout?: boolean
@@ -39,6 +40,7 @@ export function createRouteNode(options: CreateRouteNodeOptions): RouteNode {
 		fullPath,
 		component,
 		searchSchema,
+		preload,
 		children = [],
 		parent,
 		isLayout = false,
@@ -50,7 +52,8 @@ export function createRouteNode(options: CreateRouteNodeOptions): RouteNode {
 	let pattern: URLPattern | undefined
 	let prefixPattern: URLPattern | undefined
 	if (!isLayout || isIndex) {
-		pattern = new URLPattern({ pathname: fullPath === '' ? '/' : fullPath })
+		const p = fullPath === '' ? '/' : fullPath
+		pattern = new URLPattern({ pathname: p === '/' ? p : `${p}{/}?` })
 	}
 	if (isLayout && !isIndex) {
 		// Layouts get a prefix pattern that matches any path starting with their fullPath.
@@ -67,6 +70,7 @@ export function createRouteNode(options: CreateRouteNodeOptions): RouteNode {
 		prefixPattern,
 		component,
 		searchSchema,
+		preload,
 		children,
 		parent,
 		isLayout,
@@ -115,6 +119,7 @@ function buildRouteNodes(configs: RouteConfig[], parentPath: string): RouteNode[
 			fullPath,
 			component: config.component,
 			searchSchema: config.searchSchema,
+			preload: config.preload,
 			children,
 			isLayout,
 			isIndex,

package/src/engine/router.ts

@@ -158,10 +158,11 @@ export class Router {
 						}
 					}
 
-					// Set pending state
+					// Set pending state with target location
 					this.setState({
 						...this.state,
 						isPending: true,
+						pendingLocation: url,
 					})
 
 					// A newer navigation has started — abandon this one
@@ -173,6 +174,7 @@ export class Router {
 							location: url,
 							matches,
 							isPending: false,
+							pendingLocation: undefined,
 							navigationState: this.adapter.getState(),
 						})
 					}
@@ -229,6 +231,22 @@ export class Router {
 		return this.buildPath(pattern, resolved)
 	}
 
+	/**
+	 * Preload a page by its page ID.
+	 * Triggers lazy component imports for all matching route nodes,
+	 * so the code is ready when the user navigates.
+	 */
+	preload(pageId: string, params?: Record<string, string>): void {
+		const path = this.buildPagePath(pageId, params)
+		const url = new URL(path, 'http://localhost')
+		const matchUrl = this.createMatchUrl(url)
+		const matches = matchRoutes(this.routes, matchUrl)
+		if (!matches) return
+		for (const match of matches) {
+			match.node.preload?.()
+		}
+	}
+
 	/**
 	 * Go back in history.
 	 */