navgo 3.0.3

package/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Route parameter bag. Keys come from named parameters or `'*'` for wildcards.
+ * For string patterns, missing optional params are `null`.
+ * For RegExp named groups, missing groups may be `undefined`.
+ */
+export type Params = Record<string, string | null | undefined>
+
+/** Built-in validator helpers shape. */
+export interface ValidatorHelpers {
+	int(opts?: {
+		min?: number | null
+		max?: number | null
+	}): (value: string | null | undefined) => boolean
+	oneOf(values: Iterable<string>): (value: string | null | undefined) => boolean
+}
+
+/** Optional per-route hooks recognized by Navaid. */
+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>
+	/** 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>>
+	/** Predicate used during match(); may be async. If it returns `false`, the route is skipped. */
+	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
+}
+
+export interface NavigationTarget {
+	url: URL
+	params: Params
+	/** The matched route tuple from your original `routes` list; `null` when unmatched (e.g. external). */
+	route: RouteTuple | null
+	/** Optional data from route loaders when available. */
+	data?: unknown
+}
+
+export interface Navigation {
+	type: 'link' | 'goto' | 'popstate' | 'leave'
+	from: NavigationTarget | null
+	to: NavigationTarget | null
+	willUnload: boolean
+	cancelled: boolean
+	/** The original browser event that initiated navigation, when available. */
+	event?: Event
+	cancel(): void
+}
+
+/** A route tuple: [pattern, data?]. The `data` may include {@link Hooks}. */
+export type RouteTuple<T = unknown> = [pattern: string | RegExp, data: T]
+
+/** Result of calling `router.match(url)` */
+export interface MatchResult<T = unknown> {
+	route: RouteTuple<T>
+	params: Params
+}
+
+export interface Router<T = unknown> {
+	/** Format `url` relative to the configured base. */
+	format(url: string): string | false
+	/** SvelteKit-like navigation that runs loaders before updating the URL. */
+	goto(url: string, opts?: { replace?: boolean }): Promise<void>
+	/** Shallow push — updates URL/state without triggering handlers. */
+	pushState(url?: string | URL, state?: any): void
+	/** Shallow replace — updates URL/state without triggering handlers. */
+	replaceState(url?: string | URL, state?: any): void
+	/** Manually preload loaders for a URL (deduped). */
+	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>
+	/** Attach history + click listeners and immediately process current location. */
+	init(): Promise<void>
+	/** Remove listeners installed by `init()`. */
+	destroy(): void
+}
+
+/** Router metadata stored under `history.state.__navaid`. */
+export interface NavaidHistoryMeta {
+	/** Monotonic index of the current history entry for scroll restoration. */
+	idx: number
+	/** Present when the entry was created via shallow `pushState`/`replaceState`. */
+	shallow?: boolean
+	/** Origin of the navigation that created this entry. */
+	type?: 'link' | 'goto' | 'popstate'
+}
+
+export interface Options {
+	/** App base path. Default '/' */
+	base?: string
+	/** Delay before hover preloading in milliseconds. Default 20. */
+	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 routing completes (data loaded, URL updated, handlers run). */
+	after_navigate?(nav: Navigation): 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
+}
+
+/** Navaid default export: class-based router. */
+export default class Navgo<T = unknown> implements Router<T> {
+	constructor(routes?: Array<RouteTuple<T>>, opts?: Options)
+	/** Built-in validator helpers (namespaced). */
+	static validators: ValidatorHelpers
+}

package/index.js

@@ -0,0 +1,641 @@
+import { parse } from 'regexparam'
+
+const ℹ = (...args) => console.debug(...args)
+
+export default class Navgo {
+	#opts = {
+		base: '/',
+		preload_delay: 20,
+		preload_on_hover: true,
+		before_navigate: undefined,
+		after_navigate: undefined,
+		url_changed: undefined,
+	}
+	#routes = []
+	#base = '/'
+	#base_rgx = /^\/+/
+	// preload cache: href -> { promise, data, error }
+	#preloads = new Map()
+	// last matched route info
+	#current = { url: null, route: null, params: {} }
+	#route_idx = 0
+	#scroll = new Map()
+	#hash_navigating = false
+	// Latest-wins nav guard: monotonic id and currently active id
+	#nav_seq = 0
+	#nav_active = 0
+
+	//
+	// Event listeners
+	//
+	#click = e => {
+		ℹ('[🧭 event:click]', { type: e?.type, target: e?.target })
+		const info = this.#link_from_event(e, true)
+		if (!info) return
+
+		const url = new URL(info.href, location.href)
+
+		// Hash-only navigation on same path: let browser handle, but track index
+		if (url.hash && url.pathname === this.#current.url.pathname) {
+			const cur_hash = location.href.split('#')[1]
+			const next_hash = url.href.split('#')[1] ?? ''
+			if (cur_hash === next_hash) {
+				// same hash: just scroll without history churn
+				e.preventDefault()
+				if (next_hash === '' || (next_hash === 'top' && !document.getElementById('top'))) {
+					scrollTo({ top: 0 })
+				} else {
+					this.#scroll_to_hash('#' + next_hash)
+				}
+				ℹ('[🧭 hash]', 'same-hash scroll')
+				return
+			}
+
+			// 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()
+		ℹ('[🧭 link]', 'intercept', { href: info.href })
+		this.goto(info.href, { replace: false }, 'link', e)
+	}
+
+	#on_popstate = ev => {
+		// ignore popstate while a hash-originating nav is in flight
+		if (this.#hash_navigating) return
+
+		const st = ev?.state?.__navaid
+		ℹ('[🧭 event:popstate]', st)
+		// Hash-only or state-only change: pathname+search unchanged -> skip loaders
+		const cur = this.#current.url
+		const target = new URL(location.href)
+		if (cur && target.pathname === cur.pathname) {
+			this.#current.url = target
+			ℹ('  - [🧭 event:popstate]', 'same path+search; skip loaders')
+			this.#apply_scroll(ev)
+			this.#opts.url_changed?.(this.#current)
+			return
+		}
+		// Explicit shallow entries (pushState/replaceState) regardless of path
+		if (st?.shallow) {
+			this.#current.url = target
+			ℹ('  - [🧭 event:popstate]', 'shallow entry; skip loaders')
+			this.#apply_scroll(ev)
+			this.#opts.url_changed?.(this.#current)
+			return
+		}
+
+		ℹ('  - [🧭 event:popstate]', { idx: st?.idx })
+		this.goto(location.href, { replace: true }, 'popstate', ev)
+	}
+	#on_hashchange = () => {
+		// if hashchange originated from a click we tracked, bump our index and persist it
+		if (this.#hash_navigating) {
+			this.#hash_navigating = false
+			const prev = history.state && typeof history.state == 'object' ? history.state : {}
+			const next_idx = this.#route_idx + 1
+			const next_state = { ...prev, __navaid: { ...prev.__navaid, idx: next_idx } }
+			history.replaceState(next_state, '', location.href)
+			this.#route_idx = next_idx
+			ℹ('[🧭 event:hashchange]', { idx: next_idx, href: location.href })
+		}
+		// update current URL snapshot and notify
+		this.#current.url = new URL(location.href)
+		this.#opts.url_changed?.(this.#current)
+	}
+
+	#hover_timer = null
+	#maybe_preload = ev => {
+		const info = this.#link_from_event(ev, ev.type === 'mousedown')
+		if (info) {
+			ℹ('[🧭 preload]', 'link hover/tap', { href: info.href })
+			this.preload(info.href)
+		}
+	}
+	#mouse_move = ev => {
+		clearTimeout(this.#hover_timer)
+		this.#hover_timer = setTimeout(() => this.#maybe_preload(ev), this.#opts.preload_delay)
+	}
+	#tap = ev => this.#maybe_preload(ev)
+
+	#before_unload = ev => {
+		// persist scroll for refresh / session restore
+		try {
+			sessionStorage.setItem(
+				`__navaid_scroll:${location.href}`,
+				JSON.stringify({ x: scrollX, y: scrollY }),
+			)
+		} catch {}
+
+		ℹ('[🧭 event:beforeunload]', 'persist scroll + guard')
+
+		const nav = this.#make_nav({
+			type: 'leave',
+			to: null,
+			willUnload: true,
+			event: ev,
+		})
+		this.#current.route?.[1]?.beforeRouteLeave?.(nav)
+		if (nav.cancelled) {
+			ℹ('[🧭 navigate]', 'cancelled by beforeRouteLeave during unload')
+			ev.preventDefault()
+			ev.returnValue = ''
+		}
+	}
+
+	//
+	// Helpers
+	//
+	#normalize(url) {
+		return '/' + (url || '').replace(/^\/|\/$/g, '')
+	}
+	/** @param {string} url @returns {string|false} */
+	format(url) {
+		if (!url) return url
+		url = this.#normalize(url)
+		const out = this.#base_rgx.test(url) && url.replace(this.#base_rgx, '/')
+		ℹ('[🧭 format]', { in: url, out })
+		return out
+	}
+	#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]
+		ℹ('[🧭 resolve]', { url_in: url_raw, url: url.href, path })
+		return path ? { url, path } : null
+	}
+
+	#link_from_event(e, check_button = false) {
+		// prettier-ignore
+		if (!e || e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || (check_button && e.button))
+			return null
+		const a = (e.composedPath()[0] || e.target)?.closest?.('a')
+		const href = a?.getAttribute?.('href')
+		return href &&
+			!a.target &&
+			!a.download &&
+			a.host === location.host &&
+			(href[0] != '/' || this.#base_rgx.test(href))
+			? { a, href }
+			: null
+	}
+
+	#check_param_validators(param_validators, params) {
+		for (const k in param_validators) {
+			const fn = param_validators[k]
+			if (typeof fn !== 'function') continue
+			if (!fn(params[k])) return false
+		}
+		return true
+	}
+
+	async #run_loaders(route, params) {
+		const ret_val = route[1].loaders?.(params)
+		return Array.isArray(ret_val) ? Promise.all(ret_val) : ret_val
+	}
+
+	/**
+	 * @returns {Navigation}
+	 */
+	#make_nav({ type, from = undefined, to = undefined, willUnload = false, event = undefined }) {
+		const from_obj =
+			from !== undefined
+				? from
+				: this.#current.url
+					? {
+							url: this.#current.url,
+							params: this.#current.params || {},
+							route: this.#current.route,
+						}
+					: null
+		return {
+			type, // 'link' | 'goto' | 'popstate' | 'leave'
+			from: from_obj,
+			to,
+			willUnload,
+			cancelled: false,
+			event,
+			cancel() {
+				this.cancelled = true
+			},
+		}
+	}
+
+	/**
+	 * 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]
+	 * @param {Event} [ev_param]
+	 * @returns {Promise<void>}
+	 */
+	async goto(url_raw = location.href, opts = {}, nav_type = 'goto', ev_param = undefined) {
+		const nav_id = ++this.#nav_seq
+		this.#nav_active = nav_id
+		const info = this.#resolve_url_and_path(url_raw)
+		if (!info) {
+			ℹ('[🧭 goto]', 'invalid url', { url: url_raw })
+			return
+		}
+		const { url, path } = info
+
+		const is_popstate = nav_type === 'popstate'
+		let nav = this.#make_nav({ type: nav_type, to: null, event: ev_param })
+		ℹ('[🧭 goto]', 'start', {
+			type: nav_type,
+			path,
+			replace: !!opts.replace,
+			popstate: is_popstate,
+		})
+
+		//
+		// beforeRouteLeave
+		//
+		this.#current.route?.[1]?.beforeRouteLeave?.(nav)
+		if (nav.cancelled) {
+			// use history.go to cancel the nav, and jump back to where we are
+			if (is_popstate) {
+				const new_idx = ev_param?.state?.__navaid?.idx
+				if (new_idx != null) {
+					const delta = new_idx - this.#route_idx
+					if (delta) {
+						ℹ('[🧭 goto]', 'cancel popstate; correcting history', {
+							delta,
+						})
+						history.go(-delta)
+					}
+				}
+			}
+			ℹ('[🧭 goto]', 'cancelled by beforeRouteLeave')
+			return
+		}
+
+		//
+		// #
+		//
+		this.#opts.before_navigate?.(nav)
+		ℹ('[🧭 hooks]', 'before_navigate', {
+			from: nav.from?.url?.href,
+			to: url.href,
+		})
+		this.#save_scroll()
+		const hit = await this.match(path)
+		if (nav_id !== this.#nav_active) return
+
+		//
+		// loaders
+		//
+		let data
+		if (hit) {
+			const pre = this.#preloads.get(path)
+			data =
+				pre?.data ??
+				(await (pre?.promise || this.#run_loaders(hit.route, hit.params)).catch(e => ({
+					__error: e,
+				})))
+			this.#preloads.delete(path)
+			ℹ('[🧭 loaders]', pre ? 'using preloaded data' : 'loaded', {
+				path,
+				preloaded: !!pre,
+				has_error: !!data?.__error,
+			})
+		}
+		if (nav_id !== this.#nav_active) return
+
+		//
+		// change URL (skip if popstate as browser changes, or first goto())
+		//
+		if (!is_popstate && !(nav_type === 'goto' && this.#current.url == null)) {
+			const next_idx = this.#route_idx + (opts.replace ? 0 : 1)
+			const prev_state =
+				history.state && typeof history.state == 'object' ? history.state : {}
+			const next_state = {
+				...prev_state,
+				__navaid: { ...prev_state.__navaid, idx: next_idx, type: nav_type },
+			}
+			history[(opts.replace ? 'replace' : 'push') + 'State'](next_state, null, url.href)
+			ℹ('[🧭 history]', opts.replace ? 'replaceState' : 'pushState', {
+				idx: next_idx,
+				href: url.href,
+			})
+			this.#route_idx = next_idx
+			if (!opts.replace) this.#clear_onward_history()
+		}
+		if (nav_id !== this.#nav_active) return
+
+		const prev = this.#current
+		this.#current = { url, route: hit?.route || null, params: hit?.params || {} }
+
+		// Build a completion nav using the previous route as `from`
+		nav = this.#make_nav({
+			type: nav_type,
+			from: prev?.url
+				? {
+						url: prev.url,
+						params: prev.params || {},
+						route: prev.route,
+					}
+				: null,
+			to: {
+				url: new URL(location.href),
+				params: hit?.params || {},
+				route: hit?.route || null,
+				data: hit ? data : { __error: { status: 404 } },
+			},
+			event: ev_param,
+		})
+		// 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,
+			to: nav.to?.url?.href,
+			type: nav.type,
+			idx: this.#route_idx,
+		})
+		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()
+		const idx = this.#route_idx + (replace ? 0 : 1)
+		const st = { ...state, __navaid: { ...state?.__navaid, shallow: true, idx } }
+		history[(replace ? 'replace' : 'push') + 'State'](st, '', u.href)
+		ℹ('[🧭 history]', replace ? 'replaceState(shallow)' : 'pushState(shallow)', {
+			idx,
+			href: u.href,
+		})
+		// Popstate handler checks state.__navaid.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 })
+		if (!replace) this.#clear_onward_history()
+		// update current URL snapshot and notify
+		this.#current.url = u
+		this.#opts.url_changed?.(this.#current)
+	}
+
+	/** @param {string|URL} [url] @param {any} [state] */
+	pushState(url, state) {
+		this.#commit_shallow(url, state, false)
+	}
+	/** @param {string|URL} [url] @param {any} [state] */
+	replaceState(url, state) {
+		this.#commit_shallow(url, state, true)
+	}
+
+	/**
+	 * Preload loaders for a URL (e.g. to prime cache).
+	 * Dedupes concurrent preloads for the same path.
+	 */
+	/** @param {string} url_raw @returns {Promise<unknown|void>} */
+	async preload(url_raw) {
+		const { path } = this.#resolve_url_and_path(url_raw) || {}
+		if (!path) {
+			ℹ('[🧭 preload]', 'invalid url', { url: url_raw })
+			return Promise.resolve()
+		}
+		// Do not preload if we're already at this path
+		if (this.format(this.#current.url?.pathname) === path) {
+			ℹ('[🧭 preload]', 'skip current path', { path })
+			return Promise.resolve()
+		}
+		const hit = await this.match(path)
+		if (!hit) {
+			ℹ('[🧭 preload]', 'no route', { path })
+			return Promise.resolve()
+		}
+
+		if (this.#preloads.has(path)) {
+			const p = this.#preloads.get(path)
+			ℹ('[🧭 preload]', 'dedupe', { path })
+			return p.promise || Promise.resolve(p.data)
+		}
+
+		const entry = {}
+		entry.promise = this.#run_loaders(hit.route, hit.params).then(data => {
+			entry.data = data
+			delete entry.promise
+			ℹ('[🧭 preload]', 'done', { path })
+			return data
+		})
+		this.#preloads.set(path, entry)
+		return entry.promise
+	}
+
+	//
+	// Core matching
+	//
+	/** @param {string} url_raw @returns {Promise<MatchResult|null>} */
+	async match(url_raw) {
+		ℹ('[🧭 match]', 'start', { url: url_raw })
+		let arr, obj
+		for (let i = 0; i < this.#routes.length; i++) {
+			obj = this.#routes[i]
+			if (!(arr = obj.pattern.exec(url_raw))) continue
+			const params = {}
+			if (obj.keys?.length) {
+				for (let j = 0; j < obj.keys.length; ) {
+					params[obj.keys[j]] = arr[++j] || null
+				}
+			} else if (arr.groups) {
+				for (const k in arr.groups) params[k] = arr.groups[k]
+			}
+
+			// per-route validators and optional async validate()
+			const hooks = obj.data[1]
+			if (
+				hooks.param_validators &&
+				!this.#check_param_validators(hooks.param_validators, params)
+			) {
+				ℹ('[🧭 match]', 'skip: param_validators', {
+					pattern: obj.data?.[0],
+				})
+				continue
+			}
+			if (hooks.validate && !(await hooks.validate(params))) {
+				ℹ('[🧭 match]', 'skip: validate', { pattern: obj.data?.[0] })
+				continue
+			}
+
+			ℹ('[🧭 match]', 'hit', { pattern: obj.data?.[0], params })
+			return { route: obj.data || null, params }
+		}
+		ℹ('[🧭 match]', 'miss', { url: url_raw })
+		return null
+	}
+
+	/** @param {RouteTuple[]} [routes] @param {Options} [opts] */
+	constructor(routes = [], opts) {
+		this.#opts = { ...this.#opts, ...opts }
+		this.#base = this.#normalize(this.#opts.base || '/')
+		this.#base_rgx =
+			this.#base == '/' ? /^\/+/ : new RegExp('^\\' + this.#base + '(?=\\/|$)\\/?', 'i')
+
+		this.#routes = routes.map(r => {
+			const pat_or_rx = r[0]
+			const pat =
+				pat_or_rx instanceof RegExp ? { pattern: pat_or_rx, keys: null } : parse(pat_or_rx)
+			pat.data = r // keep original tuple: [pattern, hooks, ...]
+			return pat
+		})
+
+		ℹ('[🧭 init]', {
+			base: this.#base,
+			routes: this.#routes.length,
+			preload_on_hover: this.#opts.preload_on_hover,
+			preload_delay: this.#opts.preload_delay,
+		})
+	}
+
+	//
+	// Lifecycle hooks
+	//
+	init() {
+		history.scrollRestoration = 'manual'
+		ℹ('[🧭 init]', 'attach listeners; scrollRestoration=manual')
+
+		addEventListener('popstate', this.#on_popstate)
+		addEventListener('click', this.#click)
+		addEventListener('beforeunload', this.#before_unload)
+		addEventListener('hashchange', this.#on_hashchange)
+
+		if (this.#opts.preload_on_hover) {
+			// @ts-expect-error
+			if (!navigator.connection?.saveData) addEventListener('mousemove', this.#mouse_move)
+			addEventListener('touchstart', this.#tap, { passive: true })
+			addEventListener('mousedown', this.#tap)
+			ℹ('[🧭 init]', 'hover preloading enabled', {
+				delay: this.#opts.preload_delay,
+			})
+		}
+
+		// ensure current history state carries our index
+		const cur_idx = history.state?.__navaid?.idx
+		if (cur_idx == null) {
+			const prev = history.state && typeof history.state == 'object' ? history.state : {}
+			const next_state = { ...prev, __navaid: { ...prev.__navaid, idx: this.#route_idx } }
+			history.replaceState(next_state, '', location.href)
+			ℹ('[🧭 history]', 'init idx', { idx: this.#route_idx })
+		} else {
+			this.#route_idx = cur_idx
+			ℹ('[🧭 history]', 'restore idx', { idx: this.#route_idx })
+		}
+
+		ℹ('[🧭 init]', 'initial goto')
+		return this.goto()
+	}
+	destroy() {
+		removeEventListener('popstate', this.#on_popstate)
+		removeEventListener('click', this.#click)
+		removeEventListener('mousemove', this.#mouse_move)
+		removeEventListener('touchstart', this.#tap)
+		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 })
+	}
+
+	#clear_onward_history() {
+		for (const k of this.#scroll.keys()) if (k > this.#route_idx) this.#scroll.delete(k)
+		ℹ('[🧭 scroll]', 'clear onward', { upto: this.#route_idx })
+	}
+
+	#apply_scroll(ctx) {
+		const hash = location.hash
+		const t = ctx?.type || ctx?.event?.type
+		requestAnimationFrame(() => {
+			// 0) Initial (first) navigation: prefer restoring session scroll
+			const is_initial = ctx && 'from' in ctx ? ctx.from == null : !t
+			if (is_initial) {
+				try {
+					const k = `__navaid_scroll:${location.href}`
+					const { x, y } = JSON.parse(sessionStorage.getItem(k))
+					sessionStorage.removeItem(k)
+					scrollTo(x, y)
+					ℹ('[🧭 scroll]', 'restore session', { x, y })
+					return
+				} catch {}
+			}
+			// 1) On back/forward, restore saved position if available
+			if (t === 'popstate') {
+				const ev_state = ctx?.state ?? ctx?.event?.state
+				const idx = ev_state?.__navaid?.idx
+				const target_idx = typeof idx === 'number' ? idx : this.#route_idx - 1
+				this.#route_idx = target_idx
+				const pos = this.#scroll.get(target_idx)
+				if (pos) {
+					scrollTo(pos.x, pos.y)
+					ℹ('[🧭 scroll]', 'restore popstate', {
+						idx: target_idx,
+						...pos,
+					})
+					return
+				}
+			}
+			// 2) If there is a hash, prefer anchor scroll
+			if (hash && this.#scroll_to_hash(hash)) {
+				ℹ('[🧭 scroll]', 'hash')
+				return
+			}
+			// 3) Default: scroll to top for new navigations
+			scrollTo(0, 0)
+			ℹ('[🧭 scroll]', 'top')
+		})
+	}
+
+	#scroll_to_hash(hash) {
+		let id = hash.slice(1)
+		if (!id) return false
+		try {
+			id = decodeURIComponent(id)
+		} catch {}
+		const el =
+			document.getElementById(id) || document.querySelector(`[name="${CSS.escape(id)}"]`)
+		el?.scrollIntoView()
+		ℹ('[🧭 scroll]', 'anchor', { id, found: !!el })
+		return !!el
+	}
+
+	/** @type {ValidatorHelpers} */
+	static validators = {
+		int(opts = {}) {
+			const { min = null, max = null } = opts
+			return v => {
+				if (typeof v !== 'string' || !/^-?\d+$/.test(v)) return false
+				const n = Number(v)
+				if (min != null && n < min) return false
+				if (max != null && n > max) return false
+				return true
+			}
+		},
+		oneOf(values) {
+			const set = new Set(values)
+			return v => set.has(v)
+		},
+	}
+}
+
+/** @typedef {import('./index.d.ts').Options} Options */
+/** @typedef {import('./index.d.ts').RouteTuple} RouteTuple */
+/** @typedef {import('./index.d.ts').MatchResult} MatchResult */
+/** @typedef {import('./index.d.ts').ValidatorHelpers} ValidatorHelpers */
+/** @typedef {import('./index.d.ts').Navigation} Navigation */

package/package.json

@@ -0,0 +1,74 @@
+{
+	"name": "navgo",
+	"version": "3.0.3",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mustafa0x/navgo.git"
+	},
+	"description": "Adavanced router",
+	"module": "./index.js",
+	"type": "module",
+	"exports": "./index.js",
+	"types": "index.d.ts",
+	"license": "MIT",
+	"author": {
+		"name": "mustafa j"
+	},
+	"scripts": {
+		"pretest": "pnpm run build",
+		"test": "vitest run",
+		"test:e2e": "playwright test",
+		"test:all": "pnpm run build && vitest run && playwright test",
+		"types": "pnpm --package=typescript@5.6.3 dlx tsc -p test/types"
+	},
+	"files": [
+		"*.d.ts",
+		"index.js"
+	],
+	"keywords": [
+		"browser",
+		"client-side",
+		"router"
+	],
+	"dependencies": {
+		"regexparam": "^3.0.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.36.0",
+		"@playwright/test": "^1.55.1",
+		"@sveltejs/vite-plugin-svelte": "^6.2.1",
+		"@tailwindcss/vite": "^4.1.13",
+		"@tsconfig/svelte": "^5.0.5",
+		"@types/node": "^24.6.0",
+		"eslint": "^9.36.0",
+		"eslint-plugin-svelte": "^3.12.4",
+		"globals": "^16.4.0",
+		"jiti": "^2.6.0",
+		"lightningcss": "^1.30.2",
+		"prettier": "^3.6.2",
+		"prettier-plugin-svelte": "^3.4.0",
+		"prettier-plugin-tailwindcss": "^0.6.14",
+		"svelte": "^5.39.7",
+		"tailwindcss": "^4.1.13",
+		"terser": "5.44.0",
+		"typescript-eslint": "^8.45.0",
+		"vite": "^7.1.7",
+		"vitest": "^2.1.3"
+	},
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"@tailwindcss/oxide",
+			"esbuild"
+		]
+	},
+	"prettier": {
+		"semi": false,
+		"singleQuote": true,
+		"tabWidth": 4,
+		"printWidth": 100,
+		"quoteProps": "as-needed",
+		"bracketSpacing": true,
+		"arrowParens": "avoid",
+		"useTabs": true
+	}
+}

package/readme.md

@@ -0,0 +1,351 @@
+## Install
+
+```
+$ pnpm install --dev navaid
+```
+
+## Usage
+
+```js
+import Navgo from 'navgo'
+
+// Define routes up front (strings or RegExp)
+const routes = [
+	['/', {}],
+	['/users/:username', {}],
+	['/books/*', {}],
+	[/articles\/(?<year>[0-9]{4})/, {}],
+	[/privacy|privacy-policy/, {}],
+	[
+		'/admin',
+		{
+			// constrain params with built-ins or your own
+			param_validators: {
+				/* id: Navaid.validators.int({ min: 1 }) */
+			},
+			// 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) {
+				if ((nav.type === 'link' || nav.type === 'nav') && !confirm('Enter admin?')) {
+					nav.cancel()
+				}
+			},
+		},
+	],
+]
+
+// Create router with options + callbacks
+const router = new Navgo(routes, {
+	base: '/',
+	before_navigate(nav) {
+		// app-level hook before loaders/URL update; may cancel
+		console.log('before_navigate', nav.type, '→', nav.to?.url.pathname)
+	},
+	after_navigate(nav) {
+		// called after routing completes; nav.to.data holds loader result
+		if (nav.to?.data?.__error?.status === 404) {
+			console.log('404 for', nav.to.url.pathname)
+			return
+		}
+
+		console.log('after_navigate', nav.to?.url.pathname, nav.to?.data)
+	},
+	url_changed(cur) {
+		// fires on shallow/hash/popstate-shallow/404 and full navigations
+		// `cur` is the router snapshot: { url: URL, route, params }
+		console.log('url_changed', cur.url.href)
+	},
+})
+
+// Long-lived router: history + <a> bindings
+// Also immediately processes the current location
+router.init()
+```
+
+## API
+
+### new Navgo(routes?, options?)
+
+Returns: `Router`
+
+#### `routes`
+
+Type: `Array<[pattern: string | RegExp, data: any]>`
+
+Each route is a tuple whose first item is the pattern and whose second item is hooks (see “Route Hooks”). Pass `{}` when no hooks are needed. Navgo returns this tuple back to you unchanged via `onRoute`.
+
+Supported pattern types:
+
+- static (`/users`)
+- named parameters (`/users/:id`)
+- nested parameters (`/users/:id/books/:title`)
+- optional parameters (`/users/:id?/books/:title?`)
+- wildcards (`/users/*`)
+- RegExp patterns (with optional named groups)
+
+Notes:
+
+- Pattern strings are matched relative to the [`base`](#base) path.
+- RegExp patterns are used as-is. Named capture groups (e.g. `(?<year>\d{4})`) become `params` keys; unnamed groups are ignored.
+
+#### `options`
+
+- `base`: `string` (default `'/'`)
+    - App base pathname. With or without leading/trailing slashes is accepted.
+- `before_navigate`: `(nav: Navigation) => void`
+    - 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.
+- `url_changed`: `(snapshot: any) => void`
+    - Fires on every URL change — shallow `pushState`/`replaceState`, 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`)
+    - Delay in ms before hover preloading triggers.
+- `preload_on_hover`: `boolean` (default `true`)
+    - When `false`, disables hover/touch preloading.
+
+Important: Navaid only processes routes that match your `base` path.
+
+### Route Hooks
+
+- param_validators?: `Record<string, (value: string|null|undefined) => boolean>`
+    - Validate params (e.g., `id: Navaid.validators.int({ min: 1 })`). Any `false` result skips the route.
+- loaders?(params): `unknown | Promise | Array<unknown|Promise>`
+    - 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`
+    - 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:
+
+```ts
+{
+  type: 'link' | 'nav' | 'popstate' | 'leave',
+  from: { url, params, route } | null,
+  to:   { url, params, route } | null,
+  willUnload: boolean,
+  cancelled: boolean,
+  event?: Event,
+  cancel(): void
+}
+```
+
+#### Order & cancellation:
+
+- Router calls `before_navigate` on the current route (leave).
+- Call `nav.cancel()` synchronously to cancel.
+    - For `link`/`nav`, it stops before URL change.
+    - For `popstate`, cancellation causes an automatic `history.go(...)` to revert to the previous index.
+    - For `leave`, cancellation triggers the native “Leave site?” dialog (behavior is browser-controlled).
+
+Example:
+
+```js
+const routes = [
+	[
+		'/admin',
+		{
+			param_validators: {
+				/* ... */
+			},
+				loaders: params => fetch('/api/admin/stats').then(r => r.json()),
+			beforeRouteLeave(nav) {
+					if (nav.type === 'link' || nav.type === 'nav') {
+					if (!confirm('Enter admin area?')) nav.cancel()
+				}
+			},
+		},
+	],
+	['/', {}],
+]
+
+const router = new Navgo(routes, { base: '/app' })
+router.init()
+```
+
+### Methods
+
+### format(uri)
+
+Returns: `String` or `false`
+
+Formats and returns a pathname relative to the [`base`](#base) path.
+
+If the `uri` **does not** begin with the `base`, then `false` will be returned instead.<br>
+Otherwise, the return value will always lead with a slash (`/`).
+
+> **Note:** This is called automatically within the [`init()`](#init) method.
+
+#### uri
+
+Type: `String`
+
+The path to format.
+
+> **Note:** Much like [`base`](#base), paths with or without leading and trailing slashes are handled identically.
+
+### goto(uri, options?)
+
+Returns: `Promise<void>`
+
+Runs any matching route `loaders` before updating the URL and then updates history. Route processing triggers `after_navigate`. Use `replace: true` to replace the current history entry.
+
+#### uri
+
+Type: `String`
+
+The desired path to navigate. If it begins with `/` and does not match the configured [`base`](#base), it will be prefixed automatically.
+
+#### options
+
+Type: `Object`
+
+- replace: `Boolean` (default `false`)
+    - When `true`, uses `history.replaceState`; otherwise `history.pushState`.
+
+### init()
+
+Attaches global listeners to synchronize your router with URL changes, which allows Navgo to respond consistently to your browser's <kbd>BACK</kbd> and <kbd>FORWARD</kbd> buttons.
+
+Events:
+
+- Responds to: `popstate` only. No synthetic events are emitted.
+
+Navgo will also bind to any `click` event(s) on anchor tags (`<a href="" />`) so long as the link has a valid `href` that matches the [`base`](#base) path. Navgo **will not** intercept links that have _any_ `target` attribute or if the link was clicked with a special modifier (<kbd>ALT</kbd>, <kbd>SHIFT</kbd>, <kbd>CMD</kbd>, or <kbd>CTRL</kbd>).
+
+While listening, link clicks are intercepted and translated into `goto()` navigations. You can also call `goto()` programmatically.
+
+In addition, `init()` wires preloading listeners (enabled by default) so route data can be fetched early:
+
+- `mousemove` (hover) — after a short delay, hovering an in-app link triggers `preload(href)`.
+- `touchstart` and `mousedown` (tap) — tapping or pressing on an in-app link also triggers `preload(href)`.
+
+Preloading applies only to in-app anchors that match the configured [`base`](#base). You can tweak this behavior with the `preload_delay` and `preload_on_hover` options.
+
+Notes:
+
+- `preload(uri)` is a no-op when `uri` formats to the current route's path (already loaded).
+
+### Scroll persistence
+
+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).
+
+### preload(uri)
+
+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?)
+
+Returns: `void`
+
+Perform a shallow history push: updates the URL/state without triggering route processing.
+
+### replaceState(url?, state?)
+
+Returns: `void`
+
+Perform a shallow history replace: updates the URL/state without triggering route processing.
+
+### destroy()
+
+Detach all listeners initialized by [`init()`](#init).
+
+## Semantics
+
+This section explains, in detail, how navigation is processed: matching, hooks, data loading, shallow routing, history behavior, and scroll restoration. The design takes cues from SvelteKit's client router (see: kit/documentation/docs/30-advanced/10-advanced-routing.md and kit/documentation/docs/30-advanced/67-shallow-routing.md).
+
+### Navigation Types
+
+- `link` — user clicked an in-app `<a>` that matches `base`.
+- `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.
+
+### Matching and Params
+
+- A route is a `[pattern, data?]` tuple.
+- `pattern` can be a string (compiled with `regexparam`) or a `RegExp`.
+- Named params from string patterns populate `params` with `string` values; optional params that do not appear are `null`.
+- Wildcards use the `'*'` key.
+- RegExp named groups also populate `params`; omitted groups can be `undefined`.
+- If `data.param_validators` is present, each `params[k]` is validated; any `false` result skips that route.
+- If `data.validate(params)` returns or resolves to `false`, the route is also skipped.
+
+### Data Flow
+
+For `link` and `goto` navigations that match a route:
+
+```
+[click <a>] or [router.goto()]
+        → beforeRouteLeave({ 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)
+```
+
+- If a loader throws/rejects, navigation continues and `after_navigate(..., with nav.to.data = { __error })` is delivered so UI can render an error state.
+- For `popstate`, loaders run before completion so content matches the target entry; this improves scroll restoration. Errors are delivered via `after_navigate` with `nav.to.data = { __error }`.
+
+### Shallow Routing
+
+Use `pushState(url, state?)` or `replaceState(url, state?)` to update the URL/state without re-running routing logic.
+
+```
+pushState/replaceState (shallow)
+    → updates history.state and URL
+    → router does not process routing on shallow operations
+```
+
+This lets you reflect UI state in the URL while deferring route transitions until a future navigation.
+
+### History Index & popstate Cancellation
+
+To enable `popstate` cancellation, Navaid stores a monotonic `idx` in `history.state.__navaid.idx`. On `popstate`, a cancelled navigation computes the delta between the target and current `idx` and calls `history.go(-delta)` to return to the prior entry.
+
+### Scroll Restoration
+
+Navgo manages scroll manually (sets `history.scrollRestoration = 'manual'`) and applies SvelteKit-like behavior:
+
+- Saves the current scroll position for the active history index.
+- On `link`/`nav` (after route commit):
+    - 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).
+
+```
+scroll flow
+    ├─ on any nav: save current scroll for current idx
+    ├─ link/goto: after navigate → hash? anchor : scroll(0,0)
+    └─ popstate: after navigate → restore saved idx position (fallback: anchor)
+```
+
+### Method-by-Method Semantics
+
+- `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`.
+- `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.
+
+### 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.
+
+Attach validators via a route tuple's `data.param_validators` to constrain matches.