navgo 3.0.4 → 3.0.6

package/index.d.ts

@@ -7,23 +7,23 @@ export type Params = Record<string, string | null | undefined>
 
 /** Built-in validator helpers shape. */
 export interface ValidatorHelpers {
-	int(opts?: {
+	int(_opts?: {
 		min?: number | null
 		max?: number | null
-	}): (value: string | null | undefined) => boolean
-	oneOf(values: Iterable<string>): (value: string | null | undefined) => boolean
+	}): (_value: string | null | undefined) => boolean
+	one_of(_values: Iterable<string>): (_value: string | null | undefined) => boolean
 }
 
 /** Optional per-route hooks recognized by Navgo. */
 export interface Hooks {
 	/** Validate params with custom per-param validators. Return `false` to skip a match. */
-	param_validators?: Record<string, (value: string | null | undefined) => boolean>
+	param_validators?: Record<string, (_value: string | null | undefined) => boolean>
 	/** Load data for a route before navigation. May return a Promise or an array of values/promises. */
-	loaders?(params: Params): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
+	loaders?(_params: Params): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
 	/** Predicate used during match(); may be async. If it returns `false`, the route is skipped. */
-	validate?(params: Params): boolean | Promise<boolean>
+	validate?(_params: Params): boolean | Promise<boolean>
 	/** Route-level navigation guard, called on the current route when leaving it. Synchronous only; call `nav.cancel()` to prevent navigation. */
-	beforeRouteLeave?(nav: Navigation): void
+	before_route_leave?(_nav: Navigation): void
 }
 
 export interface NavigationTarget {
@@ -39,7 +39,7 @@ export interface Navigation {
 	type: 'link' | 'goto' | 'popstate' | 'leave'
 	from: NavigationTarget | null
 	to: NavigationTarget | null
-	willUnload: boolean
+	will_unload: boolean
 	cancelled: boolean
 	/** The original browser event that initiated navigation, when available. */
 	event?: Event
@@ -62,7 +62,7 @@ export type Router<T = unknown> = Navgo<T>
 export interface NavgoHistoryMeta {
 	/** Monotonic index of the current history entry for scroll restoration. */
 	idx: number
-	/** Present when the entry was created via shallow `pushState`/`replaceState`. */
+	/** Present when the entry was created via shallow `push_state`/`replace_state`. */
 	shallow?: boolean
 	/** Origin of the navigation that created this entry. */
 	type?: 'link' | 'goto' | 'popstate'
@@ -75,32 +75,37 @@ export interface Options {
 	preload_delay?: number
 	/** Disable hover/touch preloading when `false`. Default true. */
 	preload_on_hover?: boolean
-	/** Global hook fired after per-route `beforeRouteLeave`, before loaders/history change. Can cancel. */
-	before_navigate?(nav: Navigation): void
+	/** Global hook fired after per-route `before_route_leave`, before loaders/history change. Can cancel. */
+	before_navigate?(_nav: Navigation): void
 	/** Global hook fired after routing completes (data loaded, URL updated, handlers run). */
-	after_navigate?(nav: Navigation): void
+	after_navigate?(_nav: Navigation): void
+	/** Optional hook awaited after `after_navigate` and before scroll handling.
+	 *  Useful for UI frameworks (e.g., Svelte) to flush DOM updates so anchor/top
+	 *  scrolling lands on the correct elements.
+	 */
+	tick?: () => void | Promise<void>
 	/** Global hook fired whenever the URL changes.
 	 *  Triggers for shallow pushes/replaces, hash changes, popstate-shallow, 404s, and full navigations.
 	 *  Receives the router's current snapshot (eg `{ url: URL, route: RouteTuple|null, params: Params }`).
 	 */
-	url_changed?(payload: any): void
+	url_changed?(_payload: any): void
 }
 
 /** Navgo default export: class-based router. */
 export default class Navgo<T = unknown> {
-	constructor(routes?: Array<RouteTuple<T>>, opts?: Options)
+	constructor(_routes?: Array<RouteTuple<T>>, _opts?: Options)
 	/** Format `url` relative to the configured base. */
-	format(url: string): string | false
+	format(_url: string): string | false
 	/** SvelteKit-like navigation that runs loaders before updating the URL. */
-	goto(url: string, opts?: { replace?: boolean }): Promise<void>
+	goto(_url: string, _opts?: { replace?: boolean }): Promise<void>
 	/** Shallow push — updates URL/state without triggering handlers. */
-	pushState(url?: string | URL, state?: any): void
+	push_state(_url?: string | URL, _state?: any): void
 	/** Shallow replace — updates URL/state without triggering handlers. */
-	replaceState(url?: string | URL, state?: any): void
+	replace_state(_url?: string | URL, _state?: any): void
 	/** Manually preload loaders for a URL (deduped). */
-	preload(url: string): Promise<unknown | void>
+	preload(_url: string): Promise<unknown | void>
 	/** Try to match `url`; returns route tuple and params or `null`. Supports async `validate`. */
-	match(url: string): Promise<MatchResult<T> | null>
+	match(_url: string): Promise<MatchResult<T> | null>
 	/** Attach history + click listeners and immediately process current location. */
 	init(): Promise<void>
 	/** Remove listeners installed by `init()`. */

package/index.js

@@ -3,6 +3,7 @@ import { parse } from 'regexparam'
 const ℹ = (...args) => {}
 
 export default class Navgo {
+	/** @type {Options} */
 	#opts = {
 		base: '/',
 		preload_delay: 20,
@@ -10,25 +11,36 @@ export default class Navgo {
 		before_navigate: undefined,
 		after_navigate: undefined,
 		url_changed: undefined,
+		tick: undefined,
 	}
+	/** @type {Array<{ pattern: RegExp, keys: string[]|null, data: RouteTuple }>} */
 	#routes = []
+	/** @type {string} */
 	#base = '/'
+	/** @type {RegExp} */
 	#base_rgx = /^\/+/
-	// preload cache: href -> { promise, data, error }
+	/** @type {Map<string, { promise?: Promise<any>, data?: any }>} */
 	#preloads = new Map()
-	// last matched route info
+	/** @type {{ url: URL|null, route: RouteTuple|null, params: Params }} */
 	#current = { url: null, route: null, params: {} }
+	/** @type {number} */
 	#route_idx = 0
-	#scroll = new Map()
+	/** @type {boolean} */
 	#hash_navigating = false
+	/** @type {Map<number, Map<string, { x: number, y: number }>>} */
+	#areas_pos = new Map()
 	// Latest-wins nav guard: monotonic id and currently active id
+	/** @type {number} */
 	#nav_seq = 0
+	/** @type {number} */
 	#nav_active = 0
+	/** @type {(e: Event) => void | null} */
+	#scroll_handler = null
 
 	//
 	// Event listeners
 	//
-	#click = e => {
+	#click = async e => {
 		ℹ('[🧭 event:click]', { type: e?.type, target: e?.target })
 		const info = this.#link_from_event(e, true)
 		if (!info) return
@@ -53,12 +65,23 @@ export default class Navgo {
 
 			// different hash on same path — let browser update URL + scroll
 			this.#hash_navigating = true
-			this.#save_scroll()
 			ℹ('[🧭 hash]', 'navigate', { href: url.href })
 			return
 		}
 
 		e.preventDefault()
+
+		// allow the browser to repaint before navigating —
+		// this prevents INP scores being penalised
+		await new Promise(fulfil => {
+			requestAnimationFrame(() => {
+				setTimeout(fulfil, 0)
+			})
+
+			// fallback for edge case where rAF doesn't fire because e.g. tab was backgrounded
+			setTimeout(fulfil, 100)
+		})
+
 		ℹ('[🧭 link]', 'intercept', { href: info.href })
 		this.goto(info.href, { replace: false }, 'link', e)
 	}
@@ -101,12 +124,28 @@ export default class Navgo {
 			history.replaceState(next_state, '', location.href)
 			this.#route_idx = next_idx
 			ℹ('[🧭 event:hashchange]', { idx: next_idx, href: location.href })
+		} else {
+			// hashchange via Back/Forward — restore previous position when hash is removed
+			const idx = history.state?.__navgo?.idx
+			if (typeof idx === 'number') this.#route_idx = idx
+			if (!location.hash) {
+				const pos = this.#areas_pos.get(this.#route_idx)?.get?.('window')
+				if (pos) {
+					scrollTo(pos.x, pos.y)
+					ℹ('[🧭 scroll]', 'restore hash-back', { idx: this.#route_idx, ...pos })
+				} else {
+					// no saved position for previous entry — default to top
+					scrollTo(0, 0)
+					ℹ('[🧭 scroll]', 'hash-back -> top')
+				}
+			}
 		}
 		// update current URL snapshot and notify
 		this.#current.url = new URL(location.href)
 		this.#opts.url_changed?.(this.#current)
 	}
 
+	/** @type {any} */
 	#hover_timer = null
 	#maybe_preload = ev => {
 		const info = this.#link_from_event(ev, ev.type === 'mousedown')
@@ -121,6 +160,24 @@ export default class Navgo {
 	}
 	#tap = ev => this.#maybe_preload(ev)
 
+	#on_scroll = e => {
+		// prevent hash from overwriting the previous entry’s saved position.
+		if (this.#hash_navigating) return
+
+		const el = e?.target
+		const id =
+			!el || el === window || el === document ? 'window' : el?.dataset?.scrollId || el?.id
+		if (!id) return
+		const pos =
+			id === 'window'
+				? { x: scrollX || 0, y: scrollY || 0 }
+				: { x: el.scrollLeft || 0, y: el.scrollTop || 0 }
+		const m = this.#areas_pos.get(this.#route_idx) || new Map()
+		m.set(String(id), pos)
+		this.#areas_pos.set(this.#route_idx, m)
+		ℹ('[🧭 scroll:set]', this.#route_idx, m)
+	}
+
 	#before_unload = ev => {
 		// persist scroll for refresh / session restore
 		try {
@@ -135,12 +192,12 @@ export default class Navgo {
 		const nav = this.#make_nav({
 			type: 'leave',
 			to: null,
-			willUnload: true,
+			will_unload: true,
 			event: ev,
 		})
-		this.#current.route?.[1]?.beforeRouteLeave?.(nav)
+		this.#current.route?.[1]?.before_route_leave?.(nav)
 		if (nav.cancelled) {
-			ℹ('[🧭 navigate]', 'cancelled by beforeRouteLeave during unload')
+			ℹ('[🧭 navigate]', 'cancelled by before_route_leave during unload')
 			ev.preventDefault()
 			ev.returnValue = ''
 		}
@@ -163,7 +220,7 @@ export default class Navgo {
 	#resolve_url_and_path(url_raw) {
 		if (url_raw[0] == '/' && !this.#base_rgx.test(url_raw)) url_raw = this.#base + url_raw
 		const url = new URL(url_raw, location.href)
-		const path = this.format(url.pathname)?.match(/[^?#]*/)?.[0]
+		const path = this.format(url.pathname).match?.(/[^?#]*/)?.[0]
 		ℹ('[🧭 resolve]', { url_in: url_raw, url: url.href, path })
 		return path ? { url, path } : null
 	}
@@ -178,7 +235,7 @@ export default class Navgo {
 			!a.target &&
 			!a.download &&
 			a.host === location.host &&
-			(href[0] != '/' || this.#base_rgx.test(href))
+			this.#base_rgx.test(a.pathname)
 			? { a, href }
 			: null
 	}
@@ -200,7 +257,7 @@ export default class Navgo {
 	/**
 	 * @returns {Navigation}
 	 */
-	#make_nav({ type, from = undefined, to = undefined, willUnload = false, event = undefined }) {
+	#make_nav({ type, from = undefined, to = undefined, will_unload = false, event = undefined }) {
 		const from_obj =
 			from !== undefined
 				? from
@@ -215,7 +272,7 @@ export default class Navgo {
 			type, // 'link' | 'goto' | 'popstate' | 'leave'
 			from: from_obj,
 			to,
-			willUnload,
+			will_unload,
 			cancelled: false,
 			event,
 			cancel() {
@@ -225,8 +282,6 @@ export default class Navgo {
 	}
 
 	/**
-	 * Programmatic navigation that runs loaders before changing URL.
-	 * Also used by popstate to unify the flow.
 	 * @param {string} [url_raw]
 	 * @param {{ replace?: boolean }} [opts]
 	 * @param {'goto'|'link'|'popstate'} [nav_type]
@@ -253,9 +308,9 @@ export default class Navgo {
 		})
 
 		//
-		// beforeRouteLeave
+		// before_route_leave
 		//
-		this.#current.route?.[1]?.beforeRouteLeave?.(nav)
+		this.#current.route?.[1]?.before_route_leave?.(nav)
 		if (nav.cancelled) {
 			// use history.go to cancel the nav, and jump back to where we are
 			if (is_popstate) {
@@ -270,7 +325,7 @@ export default class Navgo {
 					}
 				}
 			}
-			ℹ('[🧭 goto]', 'cancelled by beforeRouteLeave')
+			ℹ('[🧭 goto]', 'cancelled by before_route_leave')
 			return
 		}
 
@@ -282,7 +337,6 @@ export default class Navgo {
 			from: nav.from?.url?.href,
 			to: url.href,
 		})
-		this.#save_scroll()
 		const hit = await this.match(path)
 		if (nav_id !== this.#nav_active) return
 
@@ -350,6 +404,7 @@ export default class Navgo {
 		})
 		// await so that apply_scroll is after potential async work
 		await this.#opts.after_navigate?.(nav)
+
 		if (nav_id !== this.#nav_active) return
 		ℹ('[🧭 navigate]', hit ? 'done' : 'done (404)', {
 			from: nav.from?.url?.href,
@@ -357,29 +412,46 @@ export default class Navgo {
 			type: nav.type,
 			idx: this.#route_idx,
 		})
+
+		// allow frameworks to flush DOM before scrolling
+		await this.#opts.tick?.()
+
 		this.#apply_scroll(nav)
 		this.#opts.url_changed?.(this.#current)
 	}
 
 	/**
 	 * Shallow push — updates the URL/state but DOES NOT call handlers or loaders.
-	 * URL changes, content stays put until a real nav.
 	 */
 	#commit_shallow(url, state, replace) {
 		const u = new URL(url || location.href, location.href)
-		// save scroll for current index before shallow change
-		this.#save_scroll()
+		// persist current entry's scroll into its state so Back after refresh restores it
+		const prev = history.state && typeof history.state == 'object' ? history.state : {}
+		history.replaceState(
+			{ ...prev, __navgo: { ...prev.__navgo, pos: { x: scrollX || 0, y: scrollY || 0 } } },
+			'',
+			location.href,
+		)
+		// also stash per-URL scroll in session storage as a fallback across reloads
+		try {
+			sessionStorage.setItem(
+				`__navgo_scroll:${location.href}`,
+				JSON.stringify({ x: scrollX || 0, y: scrollY || 0 }),
+			)
+		} catch {}
 		const idx = this.#route_idx + (replace ? 0 : 1)
-		const st = { ...state, __navaid: { ...state?.__navaid, shallow: true, idx } }
+		const st = { ...state, __navgo: { ...state?.__navgo, shallow: true, idx } }
 		history[(replace ? 'replace' : 'push') + 'State'](st, '', u.href)
-		ℹ('[🧭 history]', replace ? 'replaceState(shallow)' : 'pushState(shallow)', {
+		ℹ('[🧭 history]', replace ? 'replace_state(shallow)' : 'push_state(shallow)', {
 			idx,
 			href: u.href,
 		})
-		// Popstate handler checks state.__navaid.shallow and skips router processing
+		// Popstate handler checks state.__navgo.shallow and skips router processing
 		this.#route_idx = idx
-		// carry forward current scroll position for the shallow entry so Forward restores correctly
-		this.#scroll.set(idx, { x: scrollX, y: scrollY })
+		// carry forward current window position for the shallow entry so Forward restores correctly
+		const m = this.#areas_pos.get(idx) || new Map()
+		m.set('window', { x: scrollX || 0, y: scrollY || 0 })
+		this.#areas_pos.set(idx, m)
 		if (!replace) this.#clear_onward_history()
 		// update current URL snapshot and notify
 		this.#current.url = u
@@ -387,11 +459,11 @@ export default class Navgo {
 	}
 
 	/** @param {string|URL} [url] @param {any} [state] */
-	pushState(url, state) {
+	push_state(url, state) {
 		this.#commit_shallow(url, state, false)
 	}
 	/** @param {string|URL} [url] @param {any} [state] */
-	replaceState(url, state) {
+	replace_state(url, state) {
 		this.#commit_shallow(url, state, true)
 	}
 
@@ -510,6 +582,8 @@ export default class Navgo {
 		addEventListener('click', this.#click)
 		addEventListener('beforeunload', this.#before_unload)
 		addEventListener('hashchange', this.#on_hashchange)
+		this.#scroll_handler = throttle(this.#on_scroll, 100)
+		addEventListener('scroll', this.#scroll_handler, { capture: true })
 
 		if (this.#opts.preload_on_hover) {
 			// @ts-expect-error
@@ -544,18 +618,12 @@ export default class Navgo {
 		removeEventListener('mousedown', this.#tap)
 		removeEventListener('beforeunload', this.#before_unload)
 		removeEventListener('hashchange', this.#on_hashchange)
-	}
-
-	//
-	// Scroll
-	//
-	#save_scroll() {
-		this.#scroll.set(this.#route_idx, { x: scrollX, y: scrollY })
-		ℹ('[🧭 scroll]', 'save', { idx: this.#route_idx, x: scrollX, y: scrollY })
+		removeEventListener('scroll', this.#scroll_handler, { capture: true })
+		this.#areas_pos.clear()
 	}
 
 	#clear_onward_history() {
-		for (const k of this.#scroll.keys()) if (k > this.#route_idx) this.#scroll.delete(k)
+		for (const k of this.#areas_pos.keys()) if (k > this.#route_idx) this.#areas_pos.delete(k)
 		ℹ('[🧭 scroll]', 'clear onward', { upto: this.#route_idx })
 	}
 
@@ -578,18 +646,36 @@ export default class Navgo {
 			// 1) On back/forward, restore saved position if available
 			if (t === 'popstate') {
 				const ev_state = ctx?.state ?? ctx?.event?.state
-				const idx = ev_state?.__navgo?.idx
+				const st = ev_state?.__navgo
+				const idx = st?.idx
 				const target_idx = typeof idx === 'number' ? idx : this.#route_idx - 1
 				this.#route_idx = target_idx
-				const pos = this.#scroll.get(target_idx)
+				const m = this.#areas_pos.get(target_idx)
+				let pos = st?.pos || m?.get?.('window')
+				if (!pos) {
+					try {
+						const k = `__navgo_scroll:${location.href}`
+						pos = JSON.parse(sessionStorage.getItem(k)) || null
+						sessionStorage.removeItem(k)
+					} catch {}
+				}
 				if (pos) {
 					scrollTo(pos.x, pos.y)
-					ℹ('[🧭 scroll]', 'restore popstate', {
-						idx: target_idx,
-						...pos,
-					})
-					return
+					// re-apply on next tick to resist late reflows (e.g. images)
+					setTimeout(() => scrollTo(pos.x, pos.y), 0)
+					ℹ('[🧭 scroll]', 'restore popstate', { idx: target_idx, ...pos })
+				}
+				for (const [id, p] of m || []) {
+					if (id === 'window') continue
+					const sel = `[data-scroll-id="${CSS.escape(id)}"],` + `#${CSS.escape(id)}`
+					const el = document.querySelector(sel)
+					if (el) {
+						el.scrollTo?.(p.x, p.y)
+						el.scrollLeft = p.x
+						el.scrollTop = p.y
+					}
 				}
+				if (pos || m) return
 			}
 			// 2) If there is a hash, prefer anchor scroll
 			if (hash && this.#scroll_to_hash(hash)) {
@@ -627,13 +713,34 @@ export default class Navgo {
 				return true
 			}
 		},
-		oneOf(values) {
+		one_of(values) {
 			const set = new Set(values)
 			return v => set.has(v)
 		},
 	}
 }
 
+function throttle(fn, ms) {
+	let t,
+		last = 0
+	return e => {
+		const now = Date.now()
+		if (now - last >= ms) {
+			last = now
+			fn(e)
+		} else {
+			clearTimeout(t)
+			t = setTimeout(
+				() => {
+					last = Date.now()
+					fn(e)
+				},
+				ms - (now - last),
+			)
+		}
+	}
+}
+
 /** @typedef {import('./index.d.ts').Options} Options */
 /** @typedef {import('./index.d.ts').RouteTuple} RouteTuple */
 /** @typedef {import('./index.d.ts').MatchResult} MatchResult */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "3.0.4",
+	"version": "3.0.6",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"
@@ -16,8 +16,10 @@
 	},
 	"scripts": {
 		"build": "perl -0777 -i -pe 's/console.debug\\(...args\\)/{}/g' index.js",
-		"prepublishOnly": "pnpm run build",
+		"prepublishOnly": "pnpm test && pnpm run build",
 		"test": "vitest run index.test.js",
+		"test:e2e": "playwright test",
+		"start:testsite": "pnpm vite dev test/site --port 5714",
 		"types": "tsc -p test/types"
 	},
 	"files": [

package/readme.md

@@ -1,7 +1,7 @@
 ## Install
 
 ```
-$ pnpm install --dev navaid
+$ pnpm install --dev navgo
 ```
 
 ## Usage
@@ -26,7 +26,7 @@ const routes = [
       // load data before URL changes; result goes to after_navigate(...)
       loaders: params => fetch('/api/admin').then(r => r.json()),
       // per-route guard; cancel synchronously to block nav
-      beforeRouteLeave(nav) {
+      before_route_leave(nav) {
         if ((nav.type === 'link' || nav.type === 'nav') && !confirm('Enter admin?')) {
           nav.cancel()
         }
@@ -51,6 +51,9 @@ const router = new Navgo(routes, {
 
     console.log('after_navigate', nav.to?.url.pathname, nav.to?.data)
   },
+  // let your framework flush DOM before scroll
+  // e.g. in Svelte: `import { tick } from 'svelte'`
+  tick: tick,
   url_changed(cur) {
     // fires on shallow/hash/popstate-shallow/404 and full navigations
     // `cur` is the router snapshot: { url: URL, route, params }
@@ -97,8 +100,10 @@ Notes:
   - App-level hook called once per navigation attempt after the per-route guard and before loaders/URL update. May call `nav.cancel()` synchronously to prevent navigation.
 - `after_navigate`: `(nav: Navigation) => void`
   - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
+- `tick`: `() => void | Promise<void>`
+  - Awaited after `after_navigate` and before scroll handling; useful for frameworks to flush DOM so anchor/top scrolling lands correctly.
 - `url_changed`: `(snapshot: any) => void`
-  - Fires on every URL change — shallow `pushState`/`replaceState`, hash changes, `popstate` shallow entries, 404s, and full navigations.
+  - Fires on every URL change — shallow `push_state`/`replace_state`, hash changes, `popstate` shallow entries, 404s, and full navigations.
   - Receives the router's current snapshot: an object like `{ url: URL, route: RouteTuple|null, params: Params }`.
   - The snapshot type is intentionally `any` and may evolve without a breaking change.
 - `preload_delay`: `number` (default `20`)
@@ -116,7 +121,7 @@ Important: Navgo only processes routes that match your `base` path.
   - Run before URL changes on `link`/`nav`. Results are cached per formatted path and forwarded to `after_navigate`.
 - validate?(params): `boolean | Promise<boolean>`
   - Predicate called during matching. If it returns or resolves to `false`, the route is skipped.
-- beforeRouteLeave?(nav): `(nav: Navigation) => void`
+- before_route_leave?(nav): `(nav: Navigation) => void`
   - Guard called once per navigation attempt on the current route (leave). Call `nav.cancel()` synchronously to prevent navigation. For `popstate`, cancellation auto-reverts the history jump.
 
 The `Navigation` object contains:
@@ -126,7 +131,7 @@ The `Navigation` object contains:
   type: 'link' | 'nav' | 'popstate' | 'leave',
   from: { url, params, route } | null,
   to:   { url, params, route } | null,
-  willUnload: boolean,
+  will_unload: boolean,
   cancelled: boolean,
   event?: Event,
   cancel(): void
@@ -152,7 +157,7 @@ const routes = [
         /* ... */
       },
       loaders: params => fetch('/api/admin/stats').then(r => r.json()),
-      beforeRouteLeave(nav) {
+      before_route_leave(nav) {
         if (nav.type === 'link' || nav.type === 'nav') {
           if (!confirm('Enter admin area?')) nav.cancel()
         }
@@ -204,7 +209,7 @@ The desired path to navigate. If it begins with `/` and does not match the confi
 Type: `Object`
 
 - replace: `Boolean` (default `false`)
-  - When `true`, uses `history.replaceState`; otherwise `history.pushState`.
+- When `true`, uses `history.replaceState`; otherwise `history.pushState`.
 
 ### init()
 
@@ -233,6 +238,26 @@ Notes:
 
 On `beforeunload`, the current scroll position is saved to `sessionStorage` and restored on the next load of the same URL (e.g., refresh or tab restore).
 
+### Scroll Restoration (areas)
+
+Navgo caches/restores scroll positions for the window and any scrollable element that has a stable identifier:
+
+- Give your element either an `id` or `data-scroll-id="..."`.
+- Navgo listens to `scroll` globally (capture) and records positions per history entry.
+- On `popstate`, it restores matching elements before paint.
+
+Example:
+
+```html
+<div id="pane" class="overflow-auto">...</div>
+```
+
+Or with a custom id:
+
+```html
+<div data-scroll-id="pane">...</div>
+```
+
 ### preload(uri)
 
 Returns: `Promise<unknown | void>`
@@ -240,13 +265,13 @@ Returns: `Promise<unknown | void>`
 Preload a route's `loaders` data for a given `uri` without navigating. Concurrent calls for the same path are deduped.
 Note: Resolves to `undefined` when the matched route has no `loaders`.
 
-### pushState(url?, state?)
+### push_state(url?, state?)
 
 Returns: `void`
 
 Perform a shallow history push: updates the URL/state without triggering route processing.
 
-### replaceState(url?, state?)
+### replace_state(url?, state?)
 
 Returns: `void`
 
@@ -266,9 +291,8 @@ This section explains, in detail, how navigation is processed: matching, hooks,
 - `goto` — programmatic navigation via `router.goto(...)`.
 - `popstate` — browser back/forward.
 - `leave` — page is unloading (refresh, external navigation, tab close) via `beforeunload`.
-- `pushState` (shallow)?
 
-The router passes the type to your route-level `beforeRouteLeave(nav)` hook.
+The router passes the type to your route-level `before_route_leave(nav)` hook.
 
 ### Matching and Params
 
@@ -286,13 +310,15 @@ For `link` and `goto` navigations that match a route:
 
 ```
 [click <a>] or [router.goto()]
-        → beforeRouteLeave({ type })  // per-route guard
+        → before_route_leave({ type })  // per-route guard
         → before_navigate(nav)        // app-level start
             → cancelled? yes → stop
             → no → run loaders(params)  // may be value, Promise, or Promise[]
             → cache data by formatted path
             → history.push/replaceState(new URL)
             → after_navigate(nav)
+            → tick()?                 // optional app-provided await before scroll
+            → scroll restore/hash/top
 ```
 
 - If a loader throws/rejects, navigation continues and `after_navigate(..., with nav.to.data = { __error })` is delivered so UI can render an error state.
@@ -300,10 +326,10 @@ For `link` and `goto` navigations that match a route:
 
 ### Shallow Routing
 
-Use `pushState(url, state?)` or `replaceState(url, state?)` to update the URL/state without re-running routing logic.
+Use `push_state(url, state?)` or `replace_state(url, state?)` to update the URL/state without re-running routing logic.
 
 ```
-pushState/replaceState (shallow)
+push_state/replace_state (shallow)
     → updates history.state and URL
     → router does not process routing on shallow operations
 ```
@@ -323,7 +349,7 @@ Navgo manages scroll manually (sets `history.scrollRestoration = 'manual'`) and
   - If the URL has a `#hash`, scroll to the matching element `id` or `[name="..."]`.
   - Otherwise, scroll to the top `(0, 0)`.
 - On `popstate`: restore the saved position for the target history index; if not found but there is a `#hash`, scroll to the anchor instead.
-- Shallow `pushState`/`replaceState` never adjust scroll (routing is skipped).
+- Shallow `push_state`/`replace_state` never adjust scroll (routing is skipped).
 
 ```
 scroll flow
@@ -336,16 +362,24 @@ scroll flow
 
 - `format(uri)` — normalizes a path relative to `base`. Returns `false` when `uri` is outside of `base`.
 - `match(uri)` — returns a Promise of `{ route, params } | null` using string/RegExp patterns and validators. Awaits an async `validate(params)` if provided.
-- `goto(uri, { replace? })` — fires route-level `beforeRouteLeave('goto')`, calls global `before_navigate`, saves scroll, runs loaders, pushes/replaces, and completes via `after_navigate`.
+- `goto(uri, { replace? })` — fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loaders, pushes/replaces, and completes via `after_navigate`.
 - `init()` — wires global listeners (`popstate`, `pushstate`, `replacestate`, click) and optional hover/tap preloading; immediately processes the current location.
 - `destroy()` — removes listeners added by `init()`.
 - `preload(uri)` — pre-executes a route's `loaders` for a path and caches the result; concurrent calls are deduped.
-- `pushState(url?, state?)` — shallow push that updates the URL and `history.state` without route processing.
-- `replaceState(url?, state?)` — shallow replace that updates the URL and `history.state` without route processing.
+- `push_state(url?, state?)` — shallow push that updates the URL and `history.state` without route processing.
+- `replace_state(url?, state?)` — shallow replace that updates the URL and `history.state` without route processing.
 
 ### Built-in Validators
 
 - `Navgo.validators.int({ min?, max? })` — `true` iff the value is an integer within optional bounds.
-- `Navgo.validators.oneOf(iterable)` — `true` iff the value is in the provided set.
+- `Navgo.validators.one_of(iterable)` — `true` iff the value is in the provided set.
 
 Attach validators via a route tuple's `data.param_validators` to constrain matches.
+
+# Credits
+
+This router integrates ideas and small portions of code from these fantastic projects:
+
+- SvelteKit — https://github.com/sveltejs/kit
+- navaid — https://github.com/lukeed/navaid
+- TanStack Router — https://github.com/TanStack/router