@buzola/router 0.0.18 → 0.0.20

package/src/__tests__/router.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, mock, spyOn } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from 'bun:test'
 import { matchRoutes } from '../engine/matcher.js'
 import { createMemoryNavigationAdapter } from '../engine/navigation-adapter.js'
 import { buildRouteTree } from '../engine/route-tree.js'
@@ -12,7 +12,7 @@ function dummyComponent() {
 function createRouter(
 	configs: RouteConfig[],
 	initialURL = 'http://localhost/',
-	options?: { persistentParams?: () => Record<string, string>; shouldIntercept?: ShouldInterceptFn },
+	options?: { persistentParams?: () => Record<string, string>; shouldIntercept?: ShouldInterceptFn; viewTransitions?: boolean },
 ) {
 	const routes = buildRouteTree(configs)
 	const adapter = createMemoryNavigationAdapter({ initialURL })
@@ -307,7 +307,27 @@ 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 on a traversal between two entries with the same URL', () => {
+		const { router, count } = createCountingRouter('http://localhost/list')
+		router.navigate('/list')
+
+		router.back()
+
+		expect(count()).toBe(1)
+	})
+
+	it('does not invalidate on an intercepted traversal between two entries with the same URL', async () => {
+		const { router, count } = createCountingRouter('http://localhost/list')
+		router.navigate('/list')
+		router.addBlocker(async () => true)
+
+		router.back()
+		await new Promise(resolve => setTimeout(resolve, 0))
+
+		expect(count()).toBe(1)
+	})
+
+	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')
@@ -317,6 +337,116 @@ describe('Router same-URL navigation', () => {
 	})
 })
 
+describe('Router scroll to top', () => {
+	// Stands in for the window the router scrolls. Other test files install a DOM, so the real global is put back.
+	const original = Object.getOwnPropertyDescriptor(globalThis, 'window')
+	const scrollTo = mock((_options: ScrollToOptions) => {})
+	beforeEach(() => {
+		scrollTo.mockClear()
+		Object.defineProperty(globalThis, 'window', { value: { scrollTo }, writable: true, configurable: true })
+	})
+	afterEach(() => {
+		if (original) {
+			Object.defineProperty(globalThis, 'window', original)
+		} else {
+			delete (globalThis as { window?: unknown }).window
+		}
+	})
+
+	// Records the scroll option of every navigation the router intercepts.
+	function createRecordingRouter() {
+		const adapter = createMemoryNavigationAdapter({ initialURL: 'http://localhost/list' })
+		const scroll: (string | undefined)[] = []
+		const recording = new Map<(event: BuzolaNavigateEvent) => void, (event: BuzolaNavigateEvent) => void>()
+		const router = new Router({
+			routes: buildRouteTree([
+				{ path: '/list', component: dummyComponent },
+				{ path: '/about', component: dummyComponent },
+			]),
+			adapter: {
+				...adapter,
+				addEventListener(type, listener) {
+					const record = (event: BuzolaNavigateEvent) =>
+						listener({
+							...event,
+							intercept(options) {
+								scroll.push(options.scroll)
+								event.intercept(options)
+							},
+						})
+					recording.set(listener, record)
+					adapter.addEventListener(type, record)
+				},
+				removeEventListener(type, listener) {
+					const record = recording.get(listener)
+					if (record) adapter.removeEventListener(type, record)
+				},
+			},
+		})
+		router.start()
+		return { router, scroll }
+	}
+
+	it('scrolls to the top itself instead of leaving it to the browser on a push', () => {
+		const { router, scroll } = createRecordingRouter()
+
+		router.navigate('/about')
+
+		expect(scroll).toEqual(['manual'])
+		expect(scrollTo).toHaveBeenCalledTimes(1)
+		expect(scrollTo).toHaveBeenCalledWith({ top: 0, left: 0, behavior: 'instant' })
+	})
+
+	it('scrolls to the top itself on a replace', () => {
+		const { router, scroll } = createRecordingRouter()
+
+		router.navigate('/about', { replace: true })
+
+		expect(scroll).toEqual(['manual'])
+		expect(scrollTo).toHaveBeenCalledTimes(1)
+	})
+
+	it('leaves a fragment to the browser', () => {
+		const { router, scroll } = createRecordingRouter()
+
+		router.navigate('/about#team')
+
+		expect(scroll).toEqual(['after-transition'])
+		expect(scrollTo).not.toHaveBeenCalled()
+	})
+
+	it('does not scroll on a traversal, whose position the browser restores', () => {
+		const { router, scroll } = createRecordingRouter()
+		router.navigate('/about')
+
+		router.back()
+
+		expect(scroll).toEqual(['manual'])
+		expect(scrollTo).toHaveBeenCalledTimes(1)
+	})
+
+	it('leaves the restore to the browser on a traversal it intercepts', async () => {
+		const { router, scroll } = createRecordingRouter()
+		router.navigate('/about')
+		router.addBlocker(async () => true)
+
+		router.back()
+		await new Promise(resolve => setTimeout(resolve, 0))
+
+		expect(scroll).toEqual(['manual', 'after-transition'])
+		expect(scrollTo).toHaveBeenCalledTimes(1)
+	})
+
+	it('does not scroll when resetScroll is false', () => {
+		const { router, scroll } = createRecordingRouter()
+
+		router.navigate('/about', { resetScroll: false })
+
+		expect(scroll).toEqual(['manual'])
+		expect(scrollTo).not.toHaveBeenCalled()
+	})
+})
+
 describe('Router focus reset', () => {
 	function createCapturingRouter(initialURL: string) {
 		const routes = buildRouteTree([
@@ -408,7 +538,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)
 
@@ -421,6 +551,165 @@ describe('Router focus reset', () => {
 	})
 })
 
+describe('Router traversals', () => {
+	const flush = () => new Promise(resolve => setTimeout(resolve, 0))
+	const configs: RouteConfig[] = [
+		{ path: '/list', component: dummyComponent },
+		{ path: '/about', component: dummyComponent },
+	]
+
+	// Safari only restores scroll reliably on the classic, non-intercepted path (see Router.start).
+	it('leaves a traversal to the browser and renders the destination once it commits', () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list')
+		router.navigate('/about')
+
+		router.back()
+
+		expect(adapter.interceptCount('traverse')).toBe(0)
+		expect(router.getState().location.pathname).toBe('/list')
+		expect(router.getState().isPending).toBe(false)
+	})
+
+	it('takes the navigation state from the entry it traverses to', () => {
+		const { router } = createRouter(configs, 'http://localhost/list')
+		router.navigate('/about', { state: { tab: 'team' } })
+		router.navigate('/list')
+
+		router.back()
+
+		expect(router.getState().navigationState).toEqual({ tab: 'team' })
+	})
+
+	it('intercepts a traversal while a blocker is registered, so the blocker can hold it', async () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list')
+		router.navigate('/about')
+		await flush()
+		const blocker = mock(async () => true)
+		router.addBlocker(blocker)
+
+		router.back()
+		await flush()
+
+		expect(adapter.interceptCount('traverse')).toBe(1)
+		expect(blocker).toHaveBeenCalledTimes(1)
+		expect(router.getState().location.pathname).toBe('/list')
+	})
+
+	// Lets a test change the navigate events the router sees.
+	function createRouterSeeing(change: (event: BuzolaNavigateEvent) => BuzolaNavigateEvent) {
+		const adapter = createMemoryNavigationAdapter({ initialURL: 'http://localhost/list' })
+		const wrapped = new Map<(event: BuzolaNavigateEvent) => void, (event: BuzolaNavigateEvent) => void>()
+		const router = new Router({
+			routes: buildRouteTree(configs),
+			adapter: {
+				...adapter,
+				addEventListener(type, listener) {
+					const changed = (event: BuzolaNavigateEvent) => listener(change(event))
+					wrapped.set(listener, changed)
+					adapter.addEventListener(type, changed)
+				},
+				removeEventListener(type, listener) {
+					const changed = wrapped.get(listener)
+					if (changed) adapter.removeEventListener(type, changed)
+				},
+			},
+		})
+		router.start()
+		return { router, adapter }
+	}
+
+	it('renders a traversal only when the browser commits it, so a cancelled one never shows', () => {
+		let commit: (() => void) | undefined
+		const { router } = createRouterSeeing(event => ({ ...event, whenCommitted: callback => (commit = callback) }))
+		router.navigate('/about')
+
+		router.back()
+		expect(router.getState().location.pathname).toBe('/about')
+
+		commit?.()
+		expect(router.getState().location.pathname).toBe('/list')
+	})
+
+	it('intercepts a traversal when the adapter cannot report its commit', () => {
+		const { router, adapter } = createRouterSeeing(({ whenCommitted: _, ...event }) => event)
+		router.navigate('/about')
+
+		router.back()
+
+		expect(adapter.interceptCount('traverse')).toBe(1)
+		expect(router.getState().location.pathname).toBe('/list')
+	})
+
+	it('leaves a forward traversal to the browser too', () => {
+		const { router, adapter } = createRouter(configs, 'http://localhost/list')
+		router.navigate('/about', { state: { tab: 'team' } })
+		router.back()
+
+		router.forward()
+
+		expect(adapter.interceptCount('traverse')).toBe(0)
+		expect(router.getState().location.pathname).toBe('/about')
+		expect(router.getState().navigationState).toEqual({ tab: 'team' })
+	})
+
+	describe('with view transitions', () => {
+		// Stands in for the document, holding each view transition update until the test runs it.
+		// Other test files install a DOM, so the real global is put back afterwards.
+		const original = Object.getOwnPropertyDescriptor(globalThis, 'document')
+		let transitions: (() => void)[] = []
+		function withDocument(viewTransitions: boolean) {
+			transitions = []
+			const document = viewTransitions ? { startViewTransition: (update: () => void) => transitions.push(update) } : {}
+			Object.defineProperty(globalThis, 'document', { value: document, writable: true, configurable: true })
+		}
+		afterEach(() => {
+			if (original) {
+				Object.defineProperty(globalThis, 'document', original)
+			} else {
+				delete (globalThis as { document?: unknown }).document
+			}
+		})
+
+		it('intercepts a traversal that runs a view transition', async () => {
+			withDocument(true)
+			const { router, adapter } = createRouter(configs, 'http://localhost/list', { viewTransitions: true })
+			router.navigate('/about')
+			await flush()
+			transitions.shift()?.()
+
+			router.back()
+			await flush()
+			transitions.shift()?.()
+
+			expect(adapter.interceptCount('traverse')).toBe(1)
+			expect(router.getState().location.pathname).toBe('/list')
+		})
+
+		it('leaves a traversal to the browser when it has no view transitions', () => {
+			withDocument(false)
+			const { router, adapter } = createRouter(configs, 'http://localhost/list', { viewTransitions: true })
+			router.navigate('/about')
+
+			router.back()
+
+			expect(adapter.interceptCount('traverse')).toBe(0)
+			expect(router.getState().location.pathname).toBe('/list')
+		})
+
+		it('drops the update of a transition that a traversal overtook', async () => {
+			withDocument(true)
+			const { router } = createRouter(configs, 'http://localhost/list')
+			router.navigate('/about', { viewTransition: true })
+			await flush()
+
+			router.back()
+			transitions.shift()?.()
+
+			expect(router.getState().location.pathname).toBe('/list')
+		})
+	})
+})
+
 describe('Router.leaveApp', () => {
 	// A catch-all 404 route matches every path on the origin, so without a release the router
 	// swallows the server's own URLs and renders "Not found" with no request ever sent.

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)