@buzola/router 0.0.18 → 0.0.20

package/src/engine/navigation-adapter.ts

@@ -26,6 +26,19 @@ export function createBrowserNavigationAdapter(): NavigationAdapter {
 			navigationType: event.navigationType as BuzolaNavigateEvent['navigationType'],
 			userInitiated: event.userInitiated,
 			viewTransition,
+			whenCommitted(callback) {
+				// The next entry change a navigation makes is this one's commit, unless it was cancelled and another
+				// navigation got there first. The destination key tells them apart (it is set on traversals).
+				// updateCurrentEntry() also fires the event, with no navigation type, and commits nothing: code that
+				// saves the scroll position into the entry being left does exactly that while the traversal is pending.
+				const key = event.destination.key
+				const onChange = (change: NavigationCurrentEntryChangeEvent) => {
+					if (change.navigationType === null) return
+					nav.removeEventListener('currententrychange', onChange)
+					if (nav.currentEntry?.key === key) callback()
+				}
+				nav.addEventListener('currententrychange', onChange)
+			},
 			intercept(options) {
 				event.intercept({
 					handler: options.handler,
@@ -113,6 +126,8 @@ export interface MemoryNavigationAdapter extends NavigationAdapter {
 	leftApp(): readonly string[]
 	/** How many reloads went through to the browser, i.e. were not intercepted. */
 	reloadCount(): number
+	/** How many navigations of each type the router intercepted. */
+	interceptCount(type: BuzolaNavigateEvent['navigationType']): number
 }
 
 export function createMemoryNavigationAdapter(
@@ -125,6 +140,7 @@ export function createMemoryNavigationAdapter(
 	const listeners = new Set<(event: BuzolaNavigateEvent) => void>()
 	const left: string[] = []
 	let reloads = 0
+	const intercepts = new Map<BuzolaNavigateEvent['navigationType'], number>()
 
 	function emitNavigateEvent(
 		url: string,
@@ -134,6 +150,7 @@ export function createMemoryNavigationAdapter(
 	): void {
 		let intercepted = false
 		let interceptHandler: (() => Promise<void>) | undefined
+		let onCommitted: (() => void) | undefined
 
 		const event: BuzolaNavigateEvent = {
 			destination: { url },
@@ -141,6 +158,9 @@ export function createMemoryNavigationAdapter(
 			navigationType,
 			userInitiated: false,
 			viewTransition,
+			whenCommitted(callback) {
+				onCommitted = callback
+			},
 			intercept(options) {
 				intercepted = true
 				interceptHandler = options.handler
@@ -152,20 +172,22 @@ export function createMemoryNavigationAdapter(
 		}
 
 		if (intercepted && interceptHandler) {
+			intercepts.set(navigationType, (intercepts.get(navigationType) ?? 0) + 1)
 			// 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(
 				() => {},
 				(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)
+			onCommitted?.()
 		}
 	}
 
@@ -231,5 +253,8 @@ export function createMemoryNavigationAdapter(
 		reloadCount() {
 			return reloads
 		},
+		interceptCount(type) {
+			return intercepts.get(type) ?? 0
+		},
 	}
 }

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 }
 }
 

package/src/engine/router.ts

@@ -47,7 +47,7 @@ export interface RouterOptions {
 	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 —
+	 * 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
@@ -146,7 +146,7 @@ export class Router {
 	 */
 	start(): () => void {
 		const handler = (event: BuzolaNavigateEvent) => {
-			// Consume the pending options before any early return — they belong to the
+			// 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
 			const explicitFocusReset = this.pendingFocusReset
@@ -191,15 +191,38 @@ export class Router {
 			}
 
 			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
+			const useViewTransition = (event.viewTransition || this.viewTransitions) && typeof document !== 'undefined'
+				&& 'startViewTransition' in document
+
+			// A traversal nobody needs to hold is left to the browser. Safari restores scroll for an intercepted
+			// traversal in a later task, and skips the restore if a wheel event reached the page in between. A trackpad
+			// back swipe always delivers some, and React always has a wheel listener, so the page comes back unscrolled
+			// and the swipe snapshot hangs for its 3 s timeout. Not intercepted, the traversal takes the browser's
+			// classic path, which switches the entry and restores scroll in one task. Rendering at the switch keeps the
+			// screen in step with the URL (an effect that replaces the entry must not hit the one being left) while
+			// the page is still in place before the restore.
+			if (event.navigationType === 'traverse' && this.blockers.size === 0 && !useViewTransition && event.whenCommitted) {
+				event.whenCommitted(() => {
+					if (this.navigationId !== currentNavId) return
+					this.commitLocation(url, matches, this.adapter.getState(), event.navigationType)
+				})
+				return
+			}
+
+			// Query-only navigations stay on the same page, so keep focus where the user left it
 			// (search boxes, filters, pagination). Path changes keep the browser's focus reset,
 			// and so do fragment changes, which must move focus to the targeted section.
 			const focusReset = explicitFocusReset
 				?? (isSamePath(this.state.location, url) && this.state.location.hash === url.hash ? 'manual' : 'after-transition')
 
+			// Safari 26.5 scrolls an intercepted push or replace to the top only in the web process. The page reports
+			// scrollY 0 while the screen stays where it was (a sticky header is gone) until the next scroll, which
+			// jumps from the old position (WebKit bug 309542, fixed in 308976@main). window.scrollTo reaches the
+			// screen, so the router scrolls to the top itself. A fragment and a traversal stay with the browser.
+			const scrollToTop = scrollBehavior === 'after-transition' && event.navigationType !== 'traverse' && url.hash === ''
+
 			event.intercept({
-				scroll: scrollBehavior,
+				scroll: scrollToTop ? 'manual' : scrollBehavior,
 				focusReset,
 				handler: async () => {
 					// Check blockers before setting pending state
@@ -218,28 +241,22 @@ export class Router {
 						pendingLocation: url,
 					})
 
-					// A newer navigation has started — abandon this one
+					// A newer navigation has started, so abandon this one
 					if (this.navigationId !== currentNavId) return
 
-					// Perform the DOM update
+					// Perform the DOM update. A view transition runs it later, by when a newer navigation may have
+					// committed its own state, so check again.
 					const doUpdate = () => {
-						const previousHref = this.state.location.href
-						this.setState({
-							location: url,
-							matches,
-							isPending: false,
-							pendingLocation: undefined,
-							navigationState: this.adapter.getState(),
-						})
-						// Going to the URL we are already on is still a navigation — a browser
-						// re-requests the document for it. Loader data is keyed by href, so it
-						// would silently keep serving stale data without an explicit invalidation.
-						if (previousHref === url.href) {
-							this.invalidateAll()
+						if (this.navigationId !== currentNavId) return
+						this.commitLocation(url, matches, this.adapter.getState(), event.navigationType)
+						// Instant even where the page sets scroll-behavior: smooth, so the jump does not animate. Safari's
+						// own reset is instant as well (Chromium's follows the CSS).
+						if (scrollToTop && typeof window !== 'undefined') {
+							window.scrollTo({ top: 0, left: 0, behavior: 'instant' })
 						}
 					}
 
-					if (useViewTransition && typeof document !== 'undefined' && 'startViewTransition' in document) {
+					if (useViewTransition) {
 						;(document as unknown as { startViewTransition: (cb: () => void) => void }).startViewTransition(doUpdate)
 					} else {
 						doUpdate()
@@ -258,6 +275,30 @@ export class Router {
 		return stop
 	}
 
+	private commitLocation(
+		url: URL,
+		matches: RouterState['matches'],
+		navigationState: unknown,
+		navigationType: BuzolaNavigateEvent['navigationType'],
+	): void {
+		const previousHref = this.state.location.href
+		this.setState({
+			location: url,
+			matches,
+			isPending: false,
+			pendingLocation: undefined,
+			navigationState,
+		})
+		// Going to the URL we are already on is still a navigation: a browser
+		// re-requests the document for it. Loader data is keyed by href, so it
+		// would silently keep serving stale data without an explicit invalidation.
+		// A traversal re-requests nothing, and reloading would shorten the page before
+		// the browser restores its scroll position.
+		if (previousHref === url.href && navigationType !== 'traverse') {
+			this.invalidateAll()
+		}
+	}
+
 	/**
 	 * 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.
@@ -284,7 +325,7 @@ export class Router {
 	}
 
 	/**
-	 * Hold the navigation while the blockers run and, if they allow it, reload the current entry —
+	 * 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.
 	 */
@@ -309,7 +350,7 @@ export class Router {
 	}
 
 	/**
-	 * Hand one navigation to the browser instead of intercepting it, for a URL the SERVER owns —
+	 * 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.
 	 *
 	 * The Navigation API offers no way for a caller to mark a navigation un-interceptable:
@@ -319,7 +360,7 @@ export class Router {
 	 *
 	 * The release is recorded BEFORE the navigation is requested and is keyed to the resolved URL, so
 	 * it cannot race the event or release some other navigation. Unlike `navigate`, the URL is passed
-	 * to the browser as given — no base path is prepended, because the target is outside the app.
+	 * to the browser as given: no base path is prepended, because the target is outside the app.
 	 */
 	leaveApp(url: string): void {
 		this.releasedURL = new URL(url, this.adapter.getCurrentURL()).href
@@ -328,7 +369,7 @@ export class Router {
 
 	/**
 	 * Navigate programmatically.
-	 * The `to` path should not include the base path — it is prepended automatically.
+	 * The `to` path should not include the base path. It is prepended automatically.
 	 */
 	navigate(to: string, options?: NavigateOptions): void {
 		if (options?.resetScroll === false) {
@@ -409,7 +450,7 @@ export class Router {
 					missing.push(paramName)
 				} else {
 					if (isCatchAll) {
-						// Catch-all values may contain slashes — insert raw
+						// Catch-all values may contain slashes: insert raw
 						result.push(value)
 					} else {
 						result.push(encodeURIComponent(value))
@@ -533,7 +574,7 @@ export class Router {
 	}
 
 	/**
-	 * Dispose the router — clear all subscribers and reset state.
+	 * Dispose the router: clear all subscribers and reset state.
 	 */
 	dispose(): void {
 		this.stopFn?.()

package/src/engine/types.ts

@@ -29,7 +29,7 @@ export type RegisteredPage = keyof BuzolaPageMap & string
 export type PageParams<P extends keyof BuzolaPageMap> = BuzolaPageMap[P]
 
 /**
- * Effective params for a page — persistent params become optional.
+ * Effective params for a page: persistent params become optional.
  * When BuzolaPersistentParams is empty (default), collapses to BuzolaPageMap[P].
  */
 export type EffectivePageParams<P extends keyof BuzolaPageMap> =
@@ -50,7 +50,7 @@ export interface StandardSchema<T = unknown> {
 	}
 }
 
-/** Route component — either a regular component or a lazy-loaded one. */
+/** Route component: either a regular component or a lazy-loaded one. */
 export type RouteComponent = ComponentType<Record<string, never>> | LazyExoticComponent<ComponentType<Record<string, never>>>
 
 /** Configuration for a single route. */
@@ -63,7 +63,7 @@ export interface RouteConfig {
 	component?: RouteComponent
 	/** Schema for validating search params (Standard Schema compatible). */
 	searchSchema?: StandardSchema
-	/** Preload function — triggers lazy component import ahead of navigation. */
+	/** Preload function: triggers lazy component import ahead of navigation. */
 	preload?: () => void
 	/** Child routes. */
 	children?: RouteConfig[]
@@ -71,7 +71,7 @@ export interface RouteConfig {
 	isLayout?: boolean
 	/** Whether this is an index route (renders at parent's exact path). */
 	isIndex?: boolean
-	/** Whether this is a pathless group (e.g., (auth) — no URL segment). */
+	/** Whether this is a pathless group (e.g., (auth), with no URL segment). */
 	isPathlessGroup?: boolean
 }
 
@@ -101,7 +101,7 @@ export interface RouteNode {
 	component?: RouteComponent
 	/** Search params schema. */
 	searchSchema?: StandardSchema
-	/** Preload function — triggers lazy component import ahead of navigation. */
+	/** Preload function: triggers lazy component import ahead of navigation. */
 	preload?: () => void
 	/** Whether this is a layout node (renders children via Outlet). */
 	isLayout: boolean
@@ -113,7 +113,7 @@ export interface RouteNode {
 
 /** A node in the segment trie used for URL matching. */
 export interface TrieNode {
-	/** Static children — exact segment match via Map lookup (O(1)). */
+	/** Static children: exact segment match via Map lookup (O(1)). */
 	staticChildren: Map<string, TrieNode>
 	/**
 	 * Dynamic child: matches any single segment. It carries no param name, because routes sharing this
@@ -168,14 +168,14 @@ export interface NavigateOptions {
 	viewTransition?: boolean
 	/**
 	 * Whether to reset scroll position after navigation.
-	 * Default is `true` (browser handles it: scroll to top on push, restore on traverse).
+	 * Default is `true`: scroll to the top (or to the `#fragment`) on push and replace, restore on traverse.
 	 * Set to `false` to preserve current scroll position.
 	 */
 	resetScroll?: boolean
 	/**
 	 * Whether the browser moves focus after navigation.
-	 * Defaults to `manual` when only the search string changes — so search boxes, filters and
-	 * pagination controls keep the caret — and to `after-transition` when the path or the hash
+	 * Defaults to `manual` when only the search string changes (so search boxes, filters and
+	 * pagination controls keep the caret), and to `after-transition` when the path or the hash
 	 * changes, so fragment links move focus to the section they target.
 	 */
 	focusReset?: 'after-transition' | 'manual'
@@ -222,6 +222,12 @@ export interface BuzolaNavigateEvent {
 	userInitiated: boolean
 	/** Whether this navigation should use View Transitions API. */
 	viewTransition?: boolean
+	/**
+	 * Run `callback` once the browser has made the destination the current entry of a navigation nobody
+	 * intercepted. It runs before the browser restores the scroll position, and not at all if the navigation
+	 * is cancelled. An adapter that cannot tell leaves it out, and the router then intercepts traversals.
+	 */
+	whenCommitted?(callback: () => void): void
 	/** Intercept the navigation and handle it client-side. */
 	intercept(
 		options: { handler: () => Promise<void>; scroll?: 'after-transition' | 'manual'; focusReset?: 'after-transition' | 'manual' },

package/src/engine/utils.ts

@@ -24,12 +24,12 @@ export function extractParamNames(pattern: string): string[] {
 }
 
 /**
- * Whether two URLs address the same page — i.e. only search/hash differ.
+ * Whether two URLs address the same page, i.e. only search/hash differ.
  * Same-path navigations (filters, sorting, pagination, search) keep the page
  * on screen and keep its loader data as stale; path changes do not.
  *
- * Note this ignores the hash. Callers that care about fragment changes — focus
- * handling, for one — have to compare `hash` themselves.
+ * Note this ignores the hash. Callers that care about fragment changes (focus
+ * handling, for one) have to compare `hash` themselves.
  */
 export function isSamePath(a: string | URL, b: string | URL): boolean {
 	const urlA = typeof a === 'string' ? new URL(a) : a

package/src/env.d.ts

@@ -37,6 +37,12 @@ interface NavigateEvent extends Event {
 	scroll(): void
 }
 
+interface NavigationCurrentEntryChangeEvent extends Event {
+	/** null when the entry changed through `updateCurrentEntry()` rather than a navigation. */
+	navigationType: 'push' | 'replace' | 'reload' | 'traverse' | null
+	from: NavigationHistoryEntry
+}
+
 interface NavigationNavigateOptions {
 	state?: unknown
 	info?: unknown
@@ -60,8 +66,10 @@ interface Navigation extends EventTarget {
 	back(options?: { info?: unknown }): NavigationResult
 	forward(options?: { info?: unknown }): NavigationResult
 	addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void
+	addEventListener(type: 'currententrychange', listener: (event: NavigationCurrentEntryChangeEvent) => void): void
 	addEventListener(type: string, listener: EventListener): void
 	removeEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void
+	removeEventListener(type: 'currententrychange', listener: (event: NavigationCurrentEntryChangeEvent) => void): void
 	removeEventListener(type: string, listener: EventListener): void
 }
 

package/src/react/hooks.ts

@@ -29,7 +29,7 @@ function useRouteContext() {
 /**
  * Type-safe navigation function.
  * Uses page IDs instead of URL patterns.
- * Persistent params are optional — resolved from current URL or fallback.
+ * Persistent params are optional: resolved from current URL or fallback.
  */
 type NavigateFn = <P extends RegisteredPage>(
 	to: P,
@@ -41,7 +41,7 @@ type NavigateFn = <P extends RegisteredPage>(
 
 /**
  * Hook to get a type-safe navigate function.
- * Navigates using page IDs — the router looks up the route pattern from the page registry.
+ * Navigates using page IDs: the router looks up the route pattern from the page registry.
  */
 export function useNavigate(): NavigateFn {
 	const router = useRouter()

package/src/react/link.tsx

@@ -2,7 +2,7 @@ import React, { useCallback, useEffect, useRef } from 'react'
 import type { EffectivePageParams, NavigateOptions, RegisteredPage } from '../engine/types.js'
 import { useRouter, useRouterState } from './hooks.js'
 
-// ─── Link props type — always type-safe via page ID ──────────────────────────
+// ─── Link props type: always type-safe via page ID ───────────────────────────
 
 type LinkPropsBase = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
 	/** Replace the current history entry instead of pushing. */
@@ -29,9 +29,9 @@ type LinkPropsBase = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>
 	asChild?: boolean
 	/**
 	 * Prefetch strategy for lazy-loaded route code.
-	 * - `'intent'` — preload on mouseEnter/focus (default)
-	 * - `'render'` — preload as soon as the Link renders
-	 * - `'none'` — disable prefetching
+	 * - `'intent'`: preload on mouseEnter/focus (default)
+	 * - `'render'`: preload as soon as the Link renders
+	 * - `'none'`: disable prefetching
 	 */
 	prefetch?: 'intent' | 'render' | 'none'
 }
@@ -44,7 +44,7 @@ export type LinkProps<P extends RegisteredPage = RegisteredPage> = [keyof Effect
 
 /**
  * Type-safe link component.
- * Uses page IDs for navigation — the router looks up the route pattern from the page registry.
+ * Uses page IDs for navigation: the router looks up the route pattern from the page registry.
  * For simple navigations, renders a native <a> and lets the Navigation API handle it.
  * Uses programmatic navigation when state, replace, resetScroll, or viewTransition is needed.
  *

package/src/react/outlet.tsx

@@ -12,7 +12,7 @@ function DefaultNotFound(): React.ReactElement {
 		},
 		isDev
 			? [
-				React.createElement('h1', { key: 'h' }, '404 — Page Not Found'),
+				React.createElement('h1', { key: 'h' }, '404: Page Not Found'),
 				React.createElement('p', { key: 'p1' }, `No route matches "${typeof window !== 'undefined' ? window.location.pathname : ''}".`),
 				React.createElement('p', {
 					key: 'p2',
@@ -74,7 +74,7 @@ export function Outlet({ fallback, errorFallback, notFound }: OutletProps): Reac
 	}, [state, depth, effectiveDepth, matches, match, routeContext.params])
 
 	if (!match) {
-		// At root depth with no matches — show 404
+		// At root depth with no matches: show 404
 		if (depth === 0 && matches.length === 0) {
 			if (notFound === null) return null
 			return (notFound ?? React.createElement(DefaultNotFound, null)) as React.ReactElement