@buzola/router 0.0.16 → 0.0.18

package/src/engine/navigation-adapter.ts

@@ -63,6 +63,9 @@ export function createBrowserNavigationAdapter(): NavigationAdapter {
 			// browser, so it must go through the plain Location API and stay cross-document.
 			window.location.assign(url)
 		},
+		reload() {
+			window.location.reload()
+		},
 		back() {
 			nav.back()
 		},
@@ -108,6 +111,8 @@ interface MemoryEntry {
 export interface MemoryNavigationAdapter extends NavigationAdapter {
 	/** URLs passed to `leaveApp`, in order. */
 	leftApp(): readonly string[]
+	/** How many reloads went through to the browser, i.e. were not intercepted. */
+	reloadCount(): number
 }
 
 export function createMemoryNavigationAdapter(
@@ -119,11 +124,12 @@ export function createMemoryNavigationAdapter(
 	let currentIndex = 0
 	const listeners = new Set<(event: BuzolaNavigateEvent) => void>()
 	const left: string[] = []
+	let reloads = 0
 
 	function emitNavigateEvent(
 		url: string,
 		navigationType: BuzolaNavigateEvent['navigationType'],
-		commitNavigation: () => void,
+		commitNavigation: (intercepted: boolean) => void,
 		viewTransition?: boolean,
 	): void {
 		let intercepted = false
@@ -146,11 +152,11 @@ 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()
-				},
+				() => {},
 				(error) => {
 					// Guard aborts are expected — rethrow unexpected errors
 					if (error instanceof Error && error.name === 'NavigationAbortedError') return
@@ -159,7 +165,7 @@ export function createMemoryNavigationAdapter(
 			)
 		} else {
 			// No interception — commit immediately
-			commitNavigation()
+			commitNavigation(false)
 		}
 	}
 
@@ -175,6 +181,12 @@ export function createMemoryNavigationAdapter(
 			left.push(resolved)
 			emitNavigateEvent(resolved, 'push', () => {})
 		},
+		reload() {
+			// An intercepted reload stays in the document; only one the router let through counts.
+			emitNavigateEvent(entries[currentIndex].url, 'reload', (intercepted) => {
+				if (!intercepted) reloads++
+			})
+		},
 		navigate(url, options) {
 			const resolved = new URL(url, entries[currentIndex].url).href
 			const type = options?.replace ? 'replace' : 'push'
@@ -216,5 +228,8 @@ export function createMemoryNavigationAdapter(
 		leftApp() {
 			return left
 		},
+		reloadCount() {
+			return reloads
+		},
 	}
 }

package/src/engine/route-tree.ts

@@ -120,6 +120,7 @@ function createTrieNode(): TrieNode {
 
 function insertIntoTrie(root: TrieNode, pattern: string, chain: RouteNode[]): void {
 	const segments = splitPathSegments(pattern)
+	const paramNames: string[] = []
 	let node = root
 
 	for (let i = 0; i < segments.length; i++) {
@@ -127,18 +128,17 @@ function insertIntoTrie(root: TrieNode, pattern: string, chain: RouteNode[]): vo
 
 		if (segment.startsWith(':') && (segment.endsWith('+') || segment.endsWith('*'))) {
 			// Catch-all segment — consumes all remaining segments
-			const paramName = segment.slice(1, -1)
-			node.catchAllChild = { paramName, chain }
+			paramNames.push(segment.slice(1, -1))
+			node.catchAllChild = { chain, paramNames }
 			return
 		}
 
 		if (segment.startsWith(':')) {
-			// Dynamic segment
-			const paramName = segment.slice(1)
-			if (!node.dynamicChild) {
-				node.dynamicChild = { paramName, node: createTrieNode() }
-			}
-			node = node.dynamicChild.node
+			// Dynamic segment. The name stays with this route, not the shared trie node: another route
+			// through the same position may call it something else.
+			paramNames.push(segment.slice(1))
+			node.dynamicChild ??= createTrieNode()
+			node = node.dynamicChild
 		} else {
 			// Static segment
 			let child = node.staticChildren.get(segment)
@@ -151,7 +151,7 @@ function insertIntoTrie(root: TrieNode, pattern: string, chain: RouteNode[]): vo
 	}
 
 	// Terminal — route matches at this trie node
-	node.route = { chain }
+	node.route = { chain, paramNames }
 }
 
 // ─── Helpers ────────────────────────────────────────────────────────────────

package/src/engine/router.ts

@@ -1,7 +1,7 @@
 import { LoaderCache } from './loader-cache.js'
 import { matchRoutes } from './matcher.js'
-import type { BlockerFn, NavigateOptions, NavigationAdapter, RouterState, RouteTree } from './types.js'
-import { extractParamNames, isSamePath, parseParamSegment } from './utils.js'
+import type { BlockerFn, BuzolaNavigateEvent, NavigateOptions, NavigationAdapter, RouterState, RouteTree, ShouldInterceptFn } from './types.js'
+import { extractParamNames, isFragmentNavigation, isSamePath, parseParamSegment } from './utils.js'
 
 /**
  * Thrown when a route guard prevents navigation.
@@ -45,6 +45,16 @@ export interface RouterOptions {
 	 * Set to 0 to always re-fetch on URL change (default).
 	 */
 	loaderCacheSize?: number
+	/**
+	 * Decides, per navigation, whether the router handles it in the current document.
+	 * Return `false` to have the browser load the destination as a new document instead —
+	 * e.g. to pick up a newly deployed build on the next in-app navigation.
+	 *
+	 * Offered every push, replace and traverse the router would otherwise intercept, except
+	 * fragment navigations. Defaults to intercepting everything. See the README for how
+	 * traversals and blockers are handled.
+	 */
+	shouldIntercept?: ShouldInterceptFn
 }
 
 /**
@@ -58,12 +68,14 @@ export class Router {
 	private readonly _basePath: string
 	private readonly persistentParamsFn?: () => Record<string, string>
 	private readonly pageRegistry: Record<string, string>
+	private readonly shouldIntercept: ShouldInterceptFn | undefined
 	private subscribers = new Set<RouterSubscriber>()
 	private invalidationListeners = new Set<() => void>()
 	private state: RouterState
 	private navigationId = 0
 	private stopFn: (() => void) | undefined
 	private releasedURL: string | undefined
+	private reloadReleased = false
 	private blockers = new Set<BlockerFn>()
 	private pendingScrollBehavior: 'after-transition' | 'manual' = 'after-transition'
 	private pendingFocusReset: 'after-transition' | 'manual' | undefined
@@ -76,6 +88,7 @@ export class Router {
 		this._basePath = options.basePath ? options.basePath.replace(/\/$/, '') : ''
 		this.persistentParamsFn = options.persistentParams
 		this.pageRegistry = options.pageRegistry ?? {}
+		this.shouldIntercept = options.shouldIntercept
 		this._loaderCache = options.loaderCacheSize ? new LoaderCache(options.loaderCacheSize) : undefined
 
 		// Initialize state from current URL
@@ -132,7 +145,7 @@ export class Router {
 	 * Call this once when the router is initialized.
 	 */
 	start(): () => void {
-		const handler = (event: import('./types.js').BuzolaNavigateEvent) => {
+		const handler = (event: BuzolaNavigateEvent) => {
 			// Consume the pending options before any early return — they belong to the
 			// navigation that armed them and must not leak into the next one.
 			const scrollBehavior = this.pendingScrollBehavior
@@ -144,7 +157,15 @@ export class Router {
 				this.releasedURL = undefined
 				return
 			}
+			if (event.navigationType === 'reload' && this.reloadReleased) {
+				this.reloadReleased = false
+				return
+			}
 			if (!event.canIntercept) return
+			if (event.navigationType === 'reload') {
+				this.handleReload(event)
+				return
+			}
 
 			const url = new URL(event.destination.url)
 			const matchUrl = this.createMatchUrl(url)
@@ -154,6 +175,21 @@ export class Router {
 				return
 			}
 
+			// The browser decides a fragment navigation against the committed entry, which runs ahead of the
+			// page on screen while a navigation is pending (e.g. a blocker dialog is open).
+			if (this.shouldIntercept && !isFragmentNavigation(this.adapter.getCurrentURL(), url)) {
+				const intercept = this.shouldIntercept({
+					destination: url,
+					from: this.state.location,
+					navigationType: event.navigationType,
+					userInitiated: event.userInitiated,
+				})
+				if (!intercept) {
+					this.handleDeclined(event)
+					return
+				}
+			}
+
 			const currentNavId = ++this.navigationId
 			const useViewTransition = event.viewTransition || this.viewTransitions
 			// Query-only navigations stay on the same page — keep focus where the user left it
@@ -222,6 +258,56 @@ export class Router {
 		return stop
 	}
 
+	/**
+	 * A reload asks for a fresh document (e.g. to recover from stale chunks after a deploy), so it goes to
+	 * the browser. Re-rendering the current route from the JavaScript already loaded would defeat it.
+	 *
+	 * Blockers still get their say. They are async and a navigation can only be let through synchronously,
+	 * so the reload is held while they run and, if they allow it, requested again and released.
+	 */
+	private handleReload(event: BuzolaNavigateEvent): void {
+		if (this.blockers.size === 0) return
+		this.reloadAfterBlockers(event)
+	}
+
+	/**
+	 * `shouldIntercept` declined this navigation, so the destination must load as a new document.
+	 *
+	 * A push or replace is simply not intercepted, and the browser performs the document navigation itself.
+	 * That does not work for a traversal, which the browser completes within the document, nor while
+	 * blockers are registered, since they are async. Those are intercepted, which commits the destination
+	 * entry, and that entry is reloaded once the blockers allow it.
+	 */
+	private handleDeclined(event: BuzolaNavigateEvent): void {
+		if (event.navigationType !== 'traverse' && this.blockers.size === 0) return
+		this.reloadAfterBlockers(event)
+	}
+
+	/**
+	 * Hold the navigation while the blockers run and, if they allow it, reload the current entry —
+	 * which is already the navigation's destination, because an intercepted navigation commits before
+	 * its handler runs.
+	 */
+	private reloadAfterBlockers(event: BuzolaNavigateEvent): void {
+		const currentNavId = ++this.navigationId
+		event.intercept({
+			scroll: 'manual',
+			focusReset: 'manual',
+			handler: async () => {
+				for (const blocker of this.blockers) {
+					if (this.navigationId !== currentNavId) return
+					const shouldProceed = await blocker()
+					if (!shouldProceed) {
+						throw new NavigationAbortedError()
+					}
+				}
+				if (this.navigationId !== currentNavId) return
+				this.reloadReleased = true
+				this.adapter.reload()
+			},
+		})
+	}
+
 	/**
 	 * Hand one navigation to the browser instead of intercepting it, for a URL the SERVER owns —
 	 * an auth handoff, a file download, a server-rendered page that happens to share this origin.

package/src/engine/types.ts

@@ -115,10 +115,13 @@ export interface RouteNode {
 export interface TrieNode {
 	/** Static children — exact segment match via Map lookup (O(1)). */
 	staticChildren: Map<string, TrieNode>
-	/** Dynamic child — matches any single segment as a named param. */
-	dynamicChild?: { paramName: string; node: TrieNode }
-	/** Catch-all child — matches all remaining segments. */
-	catchAllChild?: { paramName: string; chain: RouteNode[] }
+	/**
+	 * Dynamic child: matches any single segment. It carries no param name, because routes sharing this
+	 * position may name it differently; each terminal names the values of its own route.
+	 */
+	dynamicChild?: TrieNode
+	/** Catch-all child: matches all remaining segments. */
+	catchAllChild?: TrieRoute
 	/** When defined, a route terminates at this trie node. */
 	route?: TrieRoute
 }
@@ -127,6 +130,8 @@ export interface TrieNode {
 export interface TrieRoute {
 	/** Match chain: array of RouteNode from root layout to leaf page. */
 	chain: RouteNode[]
+	/** This route's param names, one per dynamic segment in path order (a catch-all name last). */
+	paramNames: string[]
 }
 
 /** Opaque route tree built from RouteConfig[]. Passed to matchRoutes() and Router. */
@@ -183,6 +188,28 @@ export interface NavigateOptions {
  */
 export type BlockerFn = () => Promise<boolean>
 
+/** A navigation the router is about to intercept, as offered to `shouldIntercept`. */
+export interface InterceptInfo {
+	/** Where the navigation goes. */
+	destination: URL
+	/**
+	 * The location the router currently shows. While a navigation is pending, this can differ from
+	 * `navigation.currentEntry`, which has already moved to that navigation's destination.
+	 */
+	from: URL
+	/** How the navigation moves through history. Reloads always go to the browser and are never offered. */
+	navigationType: 'push' | 'replace' | 'traverse'
+	/** Whether the user initiated the navigation (e.g., clicking a link). */
+	userInitiated: boolean
+}
+
+/**
+ * Decides whether the router handles a navigation in the current document.
+ * Return `false` to have the browser load the destination as a new document instead.
+ * Called synchronously from the `navigate` event, so it cannot await anything.
+ */
+export type ShouldInterceptFn = (info: InterceptInfo) => boolean
+
 /** Navigate event from the Navigation API (simplified). */
 export interface BuzolaNavigateEvent {
 	/** The destination URL. */
@@ -212,6 +239,8 @@ export interface NavigationAdapter {
 	 * The router pairs this with a release so its own listener does not intercept the result.
 	 */
 	leaveApp(url: string): void
+	/** Reload the current document, as `location.reload()` does. */
+	reload(): void
 	/** Go back. */
 	back(): void
 	/** Go forward. */

package/src/engine/utils.ts

@@ -36,3 +36,16 @@ export function isSamePath(a: string | URL, b: string | URL): boolean {
 	const urlB = typeof b === 'string' ? new URL(b) : b
 	return urlA.origin === urlB.origin && urlA.pathname === urlB.pathname
 }
+
+/**
+ * Whether going from `from` to `to` is a fragment navigation: the URLs differ at most in the hash and `to`
+ * has one. Browsers always perform those within the current document, whether intercepted or not.
+ */
+export function isFragmentNavigation(from: URL, to: URL): boolean {
+	if (to.hash === '') return false
+	const fromWithoutHash = new URL(from)
+	fromWithoutHash.hash = ''
+	const toWithoutHash = new URL(to)
+	toWithoutHash.hash = ''
+	return fromWithoutHash.href === toWithoutHash.href
+}

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
 	BuzolaPageMap,
 	BuzolaPersistentParams,
 	EffectivePageParams,
+	InterceptInfo,
 	NavigateOptions,
 	NavigationAdapter,
 	PageParams,
@@ -29,6 +30,7 @@ export type {
 	RouteNode,
 	RouterState,
 	RouteTree,
+	ShouldInterceptFn,
 	StandardSchema,
 } from './engine/types.js'
 

package/src/react/provider.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react'
 import { createBrowserNavigationAdapter } from '../engine/navigation-adapter.js'
 import { Router } from '../engine/router.js'
-import type { RouteMatch, RouteTree } from '../engine/types.js'
+import type { RouteMatch, RouteTree, ShouldInterceptFn } from '../engine/types.js'
 import { RouteContext, type RouteContextValue, RouterContext } from './context.js'
 import { Outlet } from './outlet.js'
 
@@ -25,12 +25,14 @@ export type BuzolaProviderProps =
 		middleware?: MiddlewareComponent
 	}
 	& (
-		| { router: Router; routes?: never; persistentParams?: never; pageRegistry?: never }
+		| { router: Router; routes?: never; persistentParams?: never; pageRegistry?: never; shouldIntercept?: never }
 		| {
 			router?: never
 			routes: RouteTree
 			persistentParams?: () => Record<string, string>
 			pageRegistry?: Record<string, string>
+			/** Decides per navigation whether the router handles it; see `RouterOptions.shouldIntercept`. */
+			shouldIntercept?: ShouldInterceptFn
 		}
 	)
 
@@ -39,6 +41,11 @@ export type BuzolaProviderProps =
  * Subscribes to router state and provides context to the React tree.
  */
 export function BuzolaProvider({ routes, children, middleware: Middleware, ...props }: BuzolaProviderProps): React.ReactElement {
+	// The router is created once, so it reads the latest prop through a ref rather than the first render's closure.
+	const shouldInterceptRef = useRef(props.shouldIntercept)
+	useLayoutEffect(() => {
+		shouldInterceptRef.current = props.shouldIntercept
+	})
 	const routerRef = useRef<Router | undefined>(props.router)
 	if (!routerRef.current) {
 		routerRef.current = new Router({
@@ -46,6 +53,7 @@ export function BuzolaProvider({ routes, children, middleware: Middleware, ...pr
 			adapter: createBrowserNavigationAdapter(),
 			persistentParams: props.persistentParams,
 			pageRegistry: props.pageRegistry,
+			shouldIntercept: info => shouldInterceptRef.current?.(info) ?? true,
 		})
 	}
 	const router = routerRef.current