@buzola/router 0.0.17 → 0.0.19

package/src/__tests__/router.test.ts

@@ -3,7 +3,7 @@ import { matchRoutes } from '../engine/matcher.js'
 import { createMemoryNavigationAdapter } from '../engine/navigation-adapter.js'
 import { buildRouteTree } from '../engine/route-tree.js'
 import { Router } from '../engine/router.js'
-import type { BuzolaNavigateEvent, NavigationAdapter, RouteConfig } from '../engine/types.js'
+import type { BuzolaNavigateEvent, InterceptInfo, NavigationAdapter, RouteConfig, ShouldInterceptFn } from '../engine/types.js'
 
 function dummyComponent() {
 	return null
@@ -12,7 +12,7 @@ function dummyComponent() {
 function createRouter(
 	configs: RouteConfig[],
 	initialURL = 'http://localhost/',
-	options?: { persistentParams?: () => Record<string, string> },
+	options?: { persistentParams?: () => Record<string, string>; shouldIntercept?: ShouldInterceptFn },
 ) {
 	const routes = buildRouteTree(configs)
 	const adapter = createMemoryNavigationAdapter({ initialURL })
@@ -307,7 +307,7 @@ describe('Router same-URL navigation', () => {
 		expect(count()).toBe(1)
 	})
 
-	it('does not invalidate when the URL changes — the href-keyed loader reloads on its own', () => {
+	it('does not invalidate when the URL changes: the href-keyed loader reloads on its own', () => {
 		const { router, count } = createCountingRouter('http://localhost/')
 
 		router.navigate('/list')
@@ -408,7 +408,7 @@ describe('Router focus reset', () => {
 		try {
 			const { router, captured } = createCapturingRouter('http://localhost/list')
 
-			// No route matches — the router bails out before intercepting
+			// No route matches: the router bails out before intercepting
 			router.navigate('/unmatched', { focusReset: 'manual' })
 			expect(captured).toHaveLength(0)
 
@@ -518,3 +518,222 @@ describe('Router reload', () => {
 		expect(router.getState().location).not.toBe(before)
 	})
 })
+
+describe('Router shouldIntercept', () => {
+	const flush = () => new Promise(resolve => setTimeout(resolve, 0))
+	const configs: RouteConfig[] = [
+		{ path: '/list', component: dummyComponent },
+		{ path: '/about', component: dummyComponent },
+	]
+
+	it('intercepts every navigation when the option is not set', () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list')
+
+		router.navigate('/about')
+		router.back()
+
+		expect(router.getState().location.pathname).toBe('/list')
+		expect(adapter.reloadCount()).toBe(0)
+	})
+
+	it('intercepts a navigation it allows', () => {
+		const { router } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => true })
+
+		router.navigate('/about')
+
+		expect(router.getState().location.pathname).toBe('/about')
+	})
+
+	it('describes the navigation it is asked about', () => {
+		const shouldIntercept = mock((info: InterceptInfo) => true)
+		const { router } = createRouter(configs, 'http://localhost/list', { shouldIntercept })
+
+		router.navigate('/about?tab=team', { replace: true })
+
+		const info = shouldIntercept.mock.calls[0][0]
+		expect(info.destination.href).toBe('http://localhost/about?tab=team')
+		expect(info.from.href).toBe('http://localhost/list')
+		expect(info.navigationType).toBe('replace')
+		expect(info.userInitiated).toBe(false)
+	})
+
+	it('lets a declined push through to the browser as a document navigation', () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => false })
+
+		router.navigate('/about')
+
+		expect(adapter.getCurrentURL().pathname).toBe('/about')
+		// The browser took it: the router neither rendered the destination nor turned it into a reload.
+		expect(router.getState().location.pathname).toBe('/list')
+		expect(adapter.reloadCount()).toBe(0)
+	})
+
+	it('lets a declined replace through to the browser as a document navigation', () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => false })
+
+		router.navigate('/about', { replace: true })
+
+		expect(adapter.getCurrentURL().pathname).toBe('/about')
+		expect(router.getState().location.pathname).toBe('/list')
+		expect(adapter.reloadCount()).toBe(0)
+	})
+
+	it('reloads at the destination of a declined traversal', () => {
+		let intercept = true
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => intercept })
+		router.navigate('/about')
+
+		intercept = false
+		router.back()
+
+		expect(adapter.getCurrentURL().pathname).toBe('/list')
+		expect(adapter.reloadCount()).toBe(1)
+		expect(router.getState().location.pathname).toBe('/about')
+	})
+
+	it('intercepts a traversal it allows', () => {
+		const shouldIntercept = mock((info: InterceptInfo) => true)
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept })
+		router.navigate('/about')
+
+		router.back()
+
+		expect(shouldIntercept.mock.calls.at(-1)?.[0].navigationType).toBe('traverse')
+		expect(router.getState().location.pathname).toBe('/list')
+		expect(adapter.reloadCount()).toBe(0)
+	})
+
+	it('is not asked about a reload, which always goes to the browser', () => {
+		const shouldIntercept = mock(() => true)
+		const { adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept })
+
+		adapter.reload()
+
+		expect(shouldIntercept).not.toHaveBeenCalled()
+		expect(adapter.reloadCount()).toBe(1)
+	})
+
+	it('is not asked about a fragment navigation, which the browser keeps in the document anyway', () => {
+		const shouldIntercept = mock(() => false)
+		const { router } = createRouter(configs, 'http://localhost/list', { shouldIntercept })
+
+		router.navigate('/list#details')
+
+		expect(shouldIntercept).not.toHaveBeenCalled()
+		expect(router.getState().location.hash).toBe('#details')
+	})
+
+	it('is asked when the path changes along with the hash', () => {
+		const shouldIntercept = mock(() => false)
+		const { router } = createRouter(configs, 'http://localhost/list#details', { shouldIntercept })
+
+		router.navigate('/about#team')
+
+		expect(shouldIntercept).toHaveBeenCalledTimes(1)
+		expect(router.getState().location.pathname).toBe('/list')
+	})
+
+	it('is asked when the hash is dropped, since that loads a document', () => {
+		const shouldIntercept = mock(() => false)
+		const { router } = createRouter(configs, 'http://localhost/list#details', { shouldIntercept })
+
+		router.navigate('/list')
+
+		expect(shouldIntercept).toHaveBeenCalledTimes(1)
+	})
+
+	it('is not asked about a URL handed to the browser with leaveApp', () => {
+		const shouldIntercept = mock(() => true)
+		const { router } = createRouter(configs, 'http://localhost/list', { shouldIntercept })
+
+		router.leaveApp('/about')
+
+		expect(shouldIntercept).not.toHaveBeenCalled()
+	})
+
+	it('asks the blockers before a declined push and then loads the destination', async () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => false })
+		const blocker = mock(async () => true)
+		router.addBlocker(blocker)
+
+		router.navigate('/about')
+		await flush()
+
+		expect(blocker).toHaveBeenCalledTimes(1)
+		expect(adapter.getCurrentURL().pathname).toBe('/about')
+		expect(adapter.reloadCount()).toBe(1)
+		expect(router.getState().location.pathname).toBe('/list')
+	})
+
+	it('does not load the destination of a declined navigation when a blocker refuses', async () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => false })
+		router.addBlocker(async () => false)
+
+		router.navigate('/about')
+		await flush()
+
+		expect(adapter.reloadCount()).toBe(0)
+		expect(adapter.getCurrentURL().pathname).toBe('/about')
+		expect(router.getState().location.pathname).toBe('/list')
+	})
+
+	it('asks the blockers before a declined traversal and then loads the destination', async () => {
+		let intercept = true
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => intercept })
+		router.navigate('/about')
+		await flush()
+		const blocker = mock(async () => true)
+		router.addBlocker(blocker)
+
+		intercept = false
+		router.back()
+		await flush()
+
+		expect(blocker).toHaveBeenCalledTimes(1)
+		expect(adapter.getCurrentURL().pathname).toBe('/list')
+		expect(adapter.reloadCount()).toBe(1)
+		expect(router.getState().location.pathname).toBe('/about')
+	})
+
+	it('does not load the destination of a declined traversal when a blocker refuses', async () => {
+		let intercept = true
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept: () => intercept })
+		router.navigate('/about')
+		await flush()
+		router.addBlocker(async () => false)
+
+		intercept = false
+		router.back()
+		await flush()
+
+		expect(adapter.reloadCount()).toBe(0)
+		expect(adapter.getCurrentURL().pathname).toBe('/list')
+		expect(router.getState().location.pathname).toBe('/about')
+	})
+
+	it('treats a fragment of the committed entry as a fragment navigation while a navigation is pending', async () => {
+		let intercept = true
+		const shouldIntercept = mock(() => intercept)
+		const { router, adapter } = createRouter(configs, 'http://localhost/list', { shouldIntercept })
+		let blockerCalls = 0
+		router.addBlocker(async () => {
+			blockerCalls++
+			// The first navigation stays pending, like one held by an open unsaved-changes dialog.
+			if (blockerCalls === 1) return new Promise<boolean>(() => {})
+			return true
+		})
+		router.navigate('/about')
+		await flush()
+		expect(adapter.getCurrentURL().pathname).toBe('/about')
+		expect(router.getState().location.pathname).toBe('/list')
+
+		intercept = false
+		router.navigate('/about#team')
+		await flush()
+
+		// The browser keeps `/about#team` in the document, so declining it would load nothing.
+		expect(shouldIntercept).toHaveBeenCalledTimes(1)
+		expect(adapter.reloadCount()).toBe(0)
+		expect(router.getState().location.href).toBe('http://localhost/about#team')
+	})
+})

package/src/__tests__/setup-dom.ts

@@ -11,7 +11,7 @@ for (const key of Object.getOwnPropertyNames(window)) {
 			configurable: true,
 		})
 	} catch {
-		// Some properties can't be set — skip them
+		// Some properties can't be set: skip them
 	}
 }
 

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

@@ -29,7 +29,7 @@ describe('createPage route type safety', () => {
 	})
 
 	it('rejects dynamic route without params', () => {
-		// @ts-expect-error — :id in route but no .params() defined
+		// @ts-expect-error: :id in route but no .params() defined
 		const _page = createPage().route('/users/:id').render(() => null)
 		expect(true).toBe(true)
 	})
@@ -45,7 +45,7 @@ describe('createPage route type safety', () => {
 	it('rejects dynamic route when param is not in schema', () => {
 		const _page = createPage()
 			.params(mockSchema<{ userId: string }>())
-			// @ts-expect-error — :id is not a key of { userId: string }
+			// @ts-expect-error: :id is not a key of { userId: string }
 			.route('/users/:id')
 			.render(({ params }) => null)
 		expect(true).toBe(true)
@@ -62,7 +62,7 @@ describe('createPage route type safety', () => {
 	it('rejects when one route param is missing from schema', () => {
 		const _page = createPage()
 			.params(mockSchema<{ userId: string }>())
-			// @ts-expect-error — :postId is not in { userId: string }
+			// @ts-expect-error: :postId is not in { userId: string }
 			.route('/users/:userId/posts/:postId')
 			.render(({ params }) => null)
 		expect(true).toBe(true)
@@ -97,14 +97,14 @@ describe('createPage catch type safety', () => {
 
 	it('no .catch() after .catch()', () => {
 		const withCatch = createPage().catch(({ error }) => <div>{error.message}</div>)
-		// @ts-expect-error — .catch() should not be available after .catch()
+		// @ts-expect-error: .catch() should not be available after .catch()
 		withCatch.catch
 		expect(true).toBe(true)
 	})
 
 	it('no .loader() after .catch()', () => {
 		const withCatch = createPage().catch(({ error }) => <div>{error.message}</div>)
-		// @ts-expect-error — .loader() should not be available after .catch()
+		// @ts-expect-error: .loader() should not be available after .catch()
 		withCatch.loader
 		expect(true).toBe(true)
 	})
@@ -125,7 +125,7 @@ describe('createPage catch type safety', () => {
 	it('.catch() handler has empty params when no schema defined', () => {
 		const _page = createPage()
 			.catch(({ params }) => {
-				// @ts-expect-error — no params defined, accessing unknown key
+				// @ts-expect-error: no params defined, accessing unknown key
 				params.anything
 				return null
 			})
@@ -144,7 +144,7 @@ describe('LinkProps type safety', () => {
 	})
 
 	it('static page rejects params', () => {
-		// @ts-expect-error — static page should not accept params
+		// @ts-expect-error: static page should not accept params
 		const _a: LinkProps<'about'> = { to: 'about', params: { foo: 'bar' } }
 		expect(true).toBe(true)
 	})
@@ -152,13 +152,13 @@ describe('LinkProps type safety', () => {
 	it('dynamic page requires params', () => {
 		const _a: LinkProps<'users/detail'> = { to: 'users/detail', params: { userId: '1' } }
 
-		// @ts-expect-error — missing required params
+		// @ts-expect-error: missing required params
 		const _b: LinkProps<'users/detail'> = { to: 'users/detail' }
 		expect(true).toBe(true)
 	})
 
 	it('dynamic page requires correct param names', () => {
-		// @ts-expect-error — wrong param name
+		// @ts-expect-error: wrong param name
 		const _a: LinkProps<'users/detail'> = { to: 'users/detail', params: { id: '1' } }
 		expect(true).toBe(true)
 	})
@@ -171,14 +171,14 @@ describe('LinkProps type safety', () => {
 
 		const _b: LinkProps<'users/posts'> = {
 			to: 'users/posts',
-			// @ts-expect-error — missing postId
+			// @ts-expect-error: missing postId
 			params: { userId: '1' },
 		}
 		expect(true).toBe(true)
 	})
 
 	it('rejects unregistered pages', () => {
-		// @ts-expect-error — page not in BuzolaPageMap
+		// @ts-expect-error: page not in BuzolaPageMap
 		const _a: LinkProps<'unknown'> = { to: 'unknown' }
 		expect(true).toBe(true)
 	})
@@ -196,7 +196,7 @@ describe('Link JSX generic inference', () => {
 	})
 
 	it('rejects params on static page', () => {
-		// @ts-expect-error — static page should not accept params
+		// @ts-expect-error: static page should not accept params
 		const _el = <Link to="about" params={{ foo: 'bar' }}>About</Link>
 		expect(true).toBe(true)
 	})
@@ -204,13 +204,13 @@ describe('Link JSX generic inference', () => {
 	it('requires params on dynamic page', () => {
 		const _el = <Link to="users/detail" params={{ userId: '1' }}>User</Link>
 
-		// @ts-expect-error — missing required params
+		// @ts-expect-error: missing required params
 		const _el2 = <Link to="users/detail">User</Link>
 		expect(true).toBe(true)
 	})
 
 	it('rejects wrong param names', () => {
-		// @ts-expect-error — wrong param name
+		// @ts-expect-error: wrong param name
 		const _el = <Link to="users/detail" params={{ id: '1' }}>User</Link>
 		expect(true).toBe(true)
 	})
@@ -218,13 +218,13 @@ describe('Link JSX generic inference', () => {
 	it('requires all params for multi-param page', () => {
 		const _ok = <Link to="users/posts" params={{ userId: '1', postId: '2' }}>Post</Link>
 
-		// @ts-expect-error — missing postId
+		// @ts-expect-error: missing postId
 		const _bad = <Link to="users/posts" params={{ userId: '1' }}>Post</Link>
 		expect(true).toBe(true)
 	})
 
 	it('rejects unregistered pages', () => {
-		// @ts-expect-error — page not in BuzolaPageMap
+		// @ts-expect-error: page not in BuzolaPageMap
 		const _el = <Link to="nope">Nope</Link>
 		expect(true).toBe(true)
 	})
@@ -258,7 +258,7 @@ describe('NavigateFn type safety', () => {
 	})
 
 	it('static page rejects params', () => {
-		// @ts-expect-error — static page should not accept params
+		// @ts-expect-error: static page should not accept params
 		noop('home', { params: { foo: 'bar' } })
 		expect(true).toBe(true)
 	})
@@ -266,19 +266,19 @@ describe('NavigateFn type safety', () => {
 	it('dynamic page requires options with params', () => {
 		noop('users/detail', { params: { userId: '1' } })
 
-		// @ts-expect-error — missing required options with params
+		// @ts-expect-error: missing required options with params
 		noop('users/detail')
 		expect(true).toBe(true)
 	})
 
 	it('dynamic page requires correct param names', () => {
-		// @ts-expect-error — wrong param name (id instead of userId)
+		// @ts-expect-error: wrong param name (id instead of userId)
 		noop('users/detail', { params: { id: '1' } })
 		expect(true).toBe(true)
 	})
 
 	it('dynamic page rejects params passed directly as options (without params wrapper)', () => {
-		// @ts-expect-error — { userId: '1' } is not valid, must be { params: { userId: '1' } }
+		// @ts-expect-error: { userId: '1' } is not valid, must be { params: { userId: '1' } }
 		noop('users/detail', { userId: '1' })
 		expect(true).toBe(true)
 	})
@@ -286,13 +286,13 @@ describe('NavigateFn type safety', () => {
 	it('multi-param page requires all params', () => {
 		noop('users/posts', { params: { userId: '1', postId: '2' } })
 
-		// @ts-expect-error — missing postId
+		// @ts-expect-error: missing postId
 		noop('users/posts', { params: { userId: '1' } })
 		expect(true).toBe(true)
 	})
 
 	it('rejects unregistered pages', () => {
-		// @ts-expect-error — page not in BuzolaPageMap
+		// @ts-expect-error: page not in BuzolaPageMap
 		noop('unknown')
 		expect(true).toBe(true)
 	})

package/src/define/create-page.tsx

@@ -156,7 +156,7 @@ function combineLoaders(loaders: LoaderFn[]): LoaderFn | undefined {
 }
 
 /**
- * Follow a loader redirect, unless it points at the URL the page is already on —
+ * Follow a loader redirect, unless it points at the URL the page is already on:
  * that navigation re-runs the loader, which returns the same redirect, forever.
  */
 function followRedirect(router: Router | null, target: BuzolaRedirect): void {

package/src/engine/loader-cache.ts

@@ -1,7 +1,7 @@
 /**
  * Global LRU cache for page loader data.
  * Shared across all page components to limit total memory usage.
- * Uses Map insertion order for LRU eviction — oldest entries are evicted first.
+ * Uses Map insertion order for LRU eviction: oldest entries are evicted first.
  */
 export class LoaderCache {
 	private cache = new Map<string, unknown>()

package/src/engine/loader-state.ts

@@ -8,7 +8,7 @@ export type LoaderInstruction =
 	| { action: 'suspend'; promise: Promise<unknown> }
 
 export interface LoaderResolveContext {
-	/** Current URL href — used for stale cache keying */
+	/** Current URL href: used for stale cache keying */
 	currentUrlHref: string
 	/** Cache key that changes on URL change or invalidation */
 	cacheKey: string
@@ -31,7 +31,7 @@ let nextId = 0
 /**
  * Manages loader data lifecycle outside of React's render cycle.
  *
- * This state survives React Suspense retries — when use() suspends, React
+ * 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.
  *
@@ -43,7 +43,7 @@ export class PageLoaderState {
 	private activeCacheKey: string | null = null
 	private activePromise: Promise<unknown> | null = null
 	private activeResolvedData: unknown
-	/** URL the currently held data was loaded for — data is cached under this href, not the active one. */
+	/** URL the currently held data was loaded for: data is cached under this href, not the active one. */
 	private resolvedUrlHref: string | null = null
 	private hasResolved = false
 	private pendingBackgroundKey: string | null = null
@@ -62,7 +62,7 @@ export class PageLoaderState {
 
 		this.handleUrlChange(currentUrlHref, loaderCache)
 
-		// ─── Same cache key — return current state ─────
+		// ─── Same cache key: return current state ─────
 		if (this.activeCacheKey === cacheKey) {
 			if (this.pendingBackgroundKey === cacheKey) {
 				return { action: 'render', data: this.activeResolvedData, isLoading: true }
@@ -110,14 +110,14 @@ export class PageLoaderState {
 		this.hasResolved = true
 	}
 
-	/** Commit background SWR success — update data and clear pending flag */
+	/** Commit background SWR success: update data and clear pending flag */
 	commitBackgroundResult(data: unknown): void {
 		this.activeResolvedData = data
 		this.resolvedUrlHref = this.activeUrlHref
 		this.pendingBackgroundKey = null
 	}
 
-	/** Mark background load as failed — next render will suspend with rejected promise */
+	/** Mark background load as failed: next render will suspend with rejected promise */
 	commitBackgroundError(): void {
 		this.hasResolved = false
 		this.pendingBackgroundKey = null
@@ -141,7 +141,7 @@ export class PageLoaderState {
 
 	private handleUrlChange(currentUrlHref: string, loaderCache: LoaderCache | undefined): void {
 		if (this.activeUrlHref !== null && this.activeUrlHref !== currentUrlHref) {
-			// URL changed — save the held data to stale cache under the href it was loaded for
+			// URL changed: save the held data to stale cache under the href it was loaded for
 			if (loaderCache && this.hasResolved && this.activeResolvedData !== undefined && this.resolvedUrlHref) {
 				this.saveToStaleCache(loaderCache, this.resolvedUrlHref, this.activeResolvedData)
 			}
@@ -152,7 +152,7 @@ export class PageLoaderState {
 				this.resolvedUrlHref = currentUrlHref
 				this.hasResolved = true
 			} else if (!isSamePath(this.activeUrlHref, currentUrlHref)) {
-				// Different path — the held data describes another page, drop it and suspend
+				// Different path: the held data describes another page, so drop it and suspend
 				this.hasResolved = false
 				this.activeResolvedData = undefined
 				this.resolvedUrlHref = null
@@ -161,7 +161,7 @@ export class PageLoaderState {
 			// keep the data as stale so resolve() serves it while the new query loads.
 			this.pendingBackgroundKey = null
 		} else if (this.activeUrlHref === null && loaderCache) {
-			// Remount — try to restore from stale cache
+			// Remount: try to restore from stale cache
 			const cached = this.restoreFromStaleCache(loaderCache, currentUrlHref)
 			if (cached.hit) {
 				this.activeResolvedData = cached.value

package/src/engine/matcher.ts

@@ -20,7 +20,7 @@ function matchTrie(
 	values: string[],
 	pathname: string,
 ): RouteMatch[] | null {
-	// All segments consumed — check if this trie node has a terminal route
+	// All segments consumed: check if this trie node has a terminal route
 	if (index === segments.length) {
 		if (node.route) {
 			return buildMatchChain(node.route, values, pathname)
@@ -30,20 +30,20 @@ function matchTrie(
 
 	const segment = segments[index]
 
-	// 1. Try static child first — O(1) Map lookup, always most specific
+	// 1. Try static child first: O(1) Map lookup, always most specific
 	const staticChild = node.staticChildren.get(segment)
 	if (staticChild) {
 		const result = matchTrie(staticChild, segments, index + 1, values, pathname)
 		if (result) return result
 	}
 
-	// 2. Try dynamic child — matches any single segment
+	// 2. Try dynamic child: matches any single segment
 	if (node.dynamicChild) {
 		const result = matchTrie(node.dynamicChild, segments, index + 1, [...values, decodeURIComponent(segment)], pathname)
 		if (result) return result
 	}
 
-	// 3. Try catch-all child — consumes all remaining segments
+	// 3. Try catch-all child: consumes all remaining segments
 	if (node.catchAllChild) {
 		const remaining = segments.slice(index).map(s => decodeURIComponent(s)).join('/')
 		return buildMatchChain(node.catchAllChild, [...values, remaining], pathname)

package/src/engine/navigation-adapter.ts

@@ -152,19 +152,19 @@ export function createMemoryNavigationAdapter(
 		}
 
 		if (intercepted && interceptHandler) {
-			// Run the handler and only commit navigation state on success.
+			// Like the browser, commit the destination entry before the handler runs. A handler that
+			// fails or reloads therefore sees the destination as the current entry.
+			commitNavigation(true)
 			void interceptHandler().then(
-				() => {
-					commitNavigation(true)
-				},
+				() => {},
 				(error) => {
-					// Guard aborts are expected — rethrow unexpected errors
+					// Guard aborts are expected: rethrow unexpected errors
 					if (error instanceof Error && error.name === 'NavigationAbortedError') return
 					throw error
 				},
 			)
 		} else {
-			// No interception — commit immediately
+			// No interception: commit immediately
 			commitNavigation(false)
 		}
 	}

package/src/engine/route-tree.ts

@@ -61,7 +61,7 @@ export function buildRouteTree(configs: RouteConfig[], parentPath = ''): RouteTr
 interface FlatEntry {
 	/** The URL pattern for matching (e.g., "/project/:id/edit"). */
 	pattern: string
-	/** Layout chain from root to leaf — each becomes a RouteMatch. */
+	/** Layout chain from root to leaf: each becomes a RouteMatch. */
 	chain: RouteNode[]
 }
 
@@ -127,7 +127,7 @@ function insertIntoTrie(root: TrieNode, pattern: string, chain: RouteNode[]): vo
 		const segment = segments[i]
 
 		if (segment.startsWith(':') && (segment.endsWith('+') || segment.endsWith('*'))) {
-			// Catch-all segment — consumes all remaining segments
+			// Catch-all segment: consumes all remaining segments
 			paramNames.push(segment.slice(1, -1))
 			node.catchAllChild = { chain, paramNames }
 			return
@@ -150,7 +150,7 @@ function insertIntoTrie(root: TrieNode, pattern: string, chain: RouteNode[]): vo
 		}
 	}
 
-	// Terminal — route matches at this trie node
+	// Terminal: route matches at this trie node
 	node.route = { chain, paramNames }
 }