@pyreon/router 0.3.0 → 0.4.0

package/lib/index.js

@@ -135,69 +135,253 @@ function stringifyQuery(query) {
 	for (const [k, v] of Object.entries(query)) parts.push(v ? `${encodeURIComponent(k)}=${encodeURIComponent(v)}` : encodeURIComponent(k));
 	return parts.length ? `?${parts.join("&")}` : "";
 }
+/** WeakMap cache: compile each RouteRecord[] once */
+const _compiledCache = /* @__PURE__ */ new WeakMap();
+function compileSegment(raw) {
+	if (raw.endsWith("*") && raw.startsWith(":")) return {
+		raw,
+		isParam: true,
+		isSplat: true,
+		isOptional: false,
+		paramName: raw.slice(1, -1)
+	};
+	if (raw.endsWith("?") && raw.startsWith(":")) return {
+		raw,
+		isParam: true,
+		isSplat: false,
+		isOptional: true,
+		paramName: raw.slice(1, -1)
+	};
+	if (raw.startsWith(":")) return {
+		raw,
+		isParam: true,
+		isSplat: false,
+		isOptional: false,
+		paramName: raw.slice(1)
+	};
+	return {
+		raw,
+		isParam: false,
+		isSplat: false,
+		isOptional: false,
+		paramName: ""
+	};
+}
+function compileRoute(route) {
+	const pattern = route.path;
+	if (pattern === "(.*)" || pattern === "*") return {
+		route,
+		isWildcard: true,
+		segments: [],
+		segmentCount: 0,
+		isStatic: false,
+		staticPath: null,
+		children: null,
+		firstSegment: null
+	};
+	const segments = pattern.split("/").filter(Boolean).map(compileSegment);
+	const isStatic = segments.every((s) => !s.isParam);
+	const staticPath = isStatic ? `/${segments.map((s) => s.raw).join("/")}` : null;
+	const first = segments.length > 0 ? segments[0] : void 0;
+	const firstSegment = first && !first.isParam ? first.raw : null;
+	return {
+		route,
+		isWildcard: false,
+		segments,
+		segmentCount: segments.length,
+		isStatic,
+		staticPath,
+		children: null,
+		firstSegment
+	};
+}
+/** Expand alias paths into additional compiled entries sharing the original RouteRecord */
+function expandAliases(r, c) {
+	if (!r.alias) return [];
+	return (Array.isArray(r.alias) ? r.alias : [r.alias]).map((aliasPath) => {
+		const { alias: _, ...withoutAlias } = r;
+		const ac = compileRoute({
+			...withoutAlias,
+			path: aliasPath
+		});
+		ac.children = c.children;
+		ac.route = r;
+		return ac;
+	});
+}
+function compileRoutes(routes) {
+	const cached = _compiledCache.get(routes);
+	if (cached) return cached;
+	const compiled = [];
+	for (const r of routes) {
+		const c = compileRoute(r);
+		if (r.children && r.children.length > 0) c.children = compileRoutes(r.children);
+		compiled.push(c);
+		compiled.push(...expandAliases(r, c));
+	}
+	_compiledCache.set(routes, compiled);
+	return compiled;
+}
+/** Extract first static segment from a segment list, or null if dynamic/empty */
+function getFirstSegment(segments) {
+	const first = segments[0];
+	if (first && !first.isParam) return first.raw;
+	return null;
+}
+/** Build a FlattenedRoute from segments + metadata */
+function makeFlatEntry(segments, chain, meta, isWildcard) {
+	const isStatic = !isWildcard && segments.every((s) => !s.isParam);
+	const hasOptional = segments.some((s) => s.isOptional);
+	let minSegs = segments.length;
+	if (hasOptional) while (minSegs > 0 && segments[minSegs - 1]?.isOptional) minSegs--;
+	return {
+		segments,
+		segmentCount: segments.length,
+		matchedChain: chain,
+		isStatic,
+		staticPath: isStatic ? `/${segments.map((s) => s.raw).join("/")}` : null,
+		meta,
+		firstSegment: getFirstSegment(segments),
+		hasSplat: segments.some((s) => s.isSplat),
+		isWildcard,
+		hasOptional,
+		minSegments: minSegs
+	};
+}
 /**
-* Match a single route pattern against a path segment.
-* Returns extracted params or null if no match.
-*
-* Supports:
-*   - Exact segments: "/about"
-*   - Param segments: "/user/:id"
-*   - Wildcard: "(.*)" matches everything
+* Flatten nested routes into leaf entries with pre-joined segments.
+* This eliminates recursion during matching for the common case.
 */
-function matchPath(pattern, path) {
-	if (pattern === "(.*)" || pattern === "*") return {};
-	const patternParts = pattern.split("/").filter(Boolean);
-	const pathParts = path.split("/").filter(Boolean);
+function flattenRoutes(compiled) {
+	const result = [];
+	flattenWalk(result, compiled, [], [], {});
+	return result;
+}
+function flattenWalk(result, routes, parentSegments, parentChain, parentMeta) {
+	for (const c of routes) flattenOne(result, c, parentSegments, [...parentChain, c.route], c.route.meta ? {
+		...parentMeta,
+		...c.route.meta
+	} : { ...parentMeta });
+}
+function flattenOne(result, c, parentSegments, chain, meta) {
+	if (c.isWildcard) {
+		result.push(makeFlatEntry(parentSegments, chain, meta, true));
+		if (c.children && c.children.length > 0) flattenWalk(result, c.children, parentSegments, chain, meta);
+		return;
+	}
+	const joined = [...parentSegments, ...c.segments];
+	if (c.children && c.children.length > 0) flattenWalk(result, c.children, joined, chain, meta);
+	result.push(makeFlatEntry(joined, chain, meta, false));
+}
+const _indexCache = /* @__PURE__ */ new WeakMap();
+/** Classify a single flattened route into the appropriate index bucket */
+function indexFlatRoute(f, staticMap, segmentMap, dynamicFirst, wildcards) {
+	if (f.isStatic && f.staticPath && !staticMap.has(f.staticPath)) staticMap.set(f.staticPath, f);
+	if (f.isWildcard) {
+		wildcards.push(f);
+		return;
+	}
+	if (f.segmentCount === 0) return;
+	if (f.firstSegment) {
+		let bucket = segmentMap.get(f.firstSegment);
+		if (!bucket) {
+			bucket = [];
+			segmentMap.set(f.firstSegment, bucket);
+		}
+		bucket.push(f);
+	} else dynamicFirst.push(f);
+}
+function buildRouteIndex(routes, compiled) {
+	const cached = _indexCache.get(routes);
+	if (cached) return cached;
+	const flattened = flattenRoutes(compiled);
+	const staticMap = /* @__PURE__ */ new Map();
+	const segmentMap = /* @__PURE__ */ new Map();
+	const dynamicFirst = [];
+	const wildcards = [];
+	for (const f of flattened) indexFlatRoute(f, staticMap, segmentMap, dynamicFirst, wildcards);
+	const index = {
+		staticMap,
+		segmentMap,
+		dynamicFirst,
+		wildcards
+	};
+	_indexCache.set(routes, index);
+	return index;
+}
+/** Split path into segments without allocating a filtered array */
+function splitPath(path) {
+	if (path === "/") return [];
+	const start = path.charCodeAt(0) === 47 ? 1 : 0;
+	const end = path.length;
+	if (start >= end) return [];
+	const parts = [];
+	let segStart = start;
+	for (let i = start; i <= end; i++) if (i === end || path.charCodeAt(i) === 47) {
+		if (i > segStart) parts.push(path.substring(segStart, i));
+		segStart = i + 1;
+	}
+	return parts;
+}
+/** Decode only if the segment contains a `%` character */
+function decodeSafe(s) {
+	return s.indexOf("%") >= 0 ? decodeURIComponent(s) : s;
+}
+/** Collect remaining path segments as a decoded splat value */
+function captureSplat(pathParts, from, pathLen) {
+	const remaining = [];
+	for (let j = from; j < pathLen; j++) {
+		const p = pathParts[j];
+		if (p !== void 0) remaining.push(decodeSafe(p));
+	}
+	return remaining.join("/");
+}
+/** Check whether a flattened route's segment count is compatible with the path length */
+function isSegmentCountCompatible(f, pathLen) {
+	if (f.segmentCount === pathLen) return true;
+	if (f.hasSplat && pathLen >= f.segmentCount) return true;
+	if (f.hasOptional && pathLen >= f.minSegments && pathLen <= f.segmentCount) return true;
+	return false;
+}
+/** Try to match a flattened route against path parts */
+function matchFlattened(f, pathParts, pathLen) {
+	if (!isSegmentCountCompatible(f, pathLen)) return null;
 	const params = {};
-	for (let i = 0; i < patternParts.length; i++) {
-		const pp = patternParts[i];
+	const segments = f.segments;
+	const count = f.segmentCount;
+	for (let i = 0; i < count; i++) {
+		const seg = segments[i];
 		const pt = pathParts[i];
-		if (pp.endsWith("*") && pp.startsWith(":")) {
-			const paramName = pp.slice(1, -1);
-			params[paramName] = pathParts.slice(i).map(decodeURIComponent).join("/");
+		if (!seg) return null;
+		if (seg.isSplat) {
+			params[seg.paramName] = captureSplat(pathParts, i, pathLen);
 			return params;
 		}
-		if (pp.startsWith(":")) params[pp.slice(1)] = decodeURIComponent(pt);
-		else if (pp !== pt) return null;
+		if (pt === void 0) {
+			if (!seg.isOptional) return null;
+			continue;
+		}
+		if (seg.isParam) params[seg.paramName] = decodeSafe(pt);
+		else if (seg.raw !== pt) return null;
 	}
-	if (patternParts.length !== pathParts.length) return null;
 	return params;
 }
-/**
-* Check if a path starts with a route's prefix (for nested route matching).
-* Returns the remaining path suffix, or null if no match.
-*/
-function matchPrefix(pattern, path) {
-	if (pattern === "(.*)" || pattern === "*") return {
-		params: {},
-		rest: path
-	};
-	const patternParts = pattern.split("/").filter(Boolean);
-	const pathParts = path.split("/").filter(Boolean);
-	if (pathParts.length < patternParts.length) return null;
-	const params = {};
-	for (let i = 0; i < patternParts.length; i++) {
-		const pp = patternParts[i];
-		const pt = pathParts[i];
-		if (pp.endsWith("*") && pp.startsWith(":")) {
-			const paramName = pp.slice(1, -1);
-			params[paramName] = pathParts.slice(i).map(decodeURIComponent).join("/");
-			return {
-				params,
-				rest: "/"
-			};
-		}
-		if (pp.startsWith(":")) params[pp.slice(1)] = decodeURIComponent(pt);
-		else if (pp !== pt) return null;
+/** Search a list of flattened candidates for a match */
+function searchCandidates(candidates, pathParts, pathLen) {
+	for (let i = 0; i < candidates.length; i++) {
+		const f = candidates[i];
+		if (!f) continue;
+		const params = matchFlattened(f, pathParts, pathLen);
+		if (params) return {
+			params,
+			matched: f.matchedChain
+		};
 	}
-	return {
-		params,
-		rest: `/${pathParts.slice(patternParts.length).join("/")}`
-	};
+	return null;
 }
 /**
 * Resolve a raw path (including query string and hash) against the route tree.
-* Handles nested routes recursively.
+* Uses flattened index for O(1) static lookup and first-segment dispatch.
 */
 function resolveRoute(rawPath, routes) {
 	const qIdx = rawPath.indexOf("?");
@@ -207,14 +391,50 @@ function resolveRoute(rawPath, routes) {
 	const cleanPath = hIdx >= 0 ? pathAndHash.slice(0, hIdx) : pathAndHash;
 	const hash = hIdx >= 0 ? pathAndHash.slice(hIdx + 1) : "";
 	const query = parseQuery(queryPart);
-	const match = matchRoutes(cleanPath, routes, []);
-	if (match) return {
+	const index = buildRouteIndex(routes, compileRoutes(routes));
+	const staticMatch = index.staticMap.get(cleanPath);
+	if (staticMatch) return {
+		path: cleanPath,
+		params: {},
+		query,
+		hash,
+		matched: staticMatch.matchedChain,
+		meta: staticMatch.meta
+	};
+	const pathParts = splitPath(cleanPath);
+	const pathLen = pathParts.length;
+	if (pathLen > 0) {
+		const first = pathParts[0];
+		const bucket = index.segmentMap.get(first);
+		if (bucket) {
+			const match = searchCandidates(bucket, pathParts, pathLen);
+			if (match) return {
+				path: cleanPath,
+				params: match.params,
+				query,
+				hash,
+				matched: match.matched,
+				meta: mergeMeta(match.matched)
+			};
+		}
+	}
+	const dynMatch = searchCandidates(index.dynamicFirst, pathParts, pathLen);
+	if (dynMatch) return {
 		path: cleanPath,
-		params: match.params,
+		params: dynMatch.params,
+		query,
+		hash,
+		matched: dynMatch.matched,
+		meta: mergeMeta(dynMatch.matched)
+	};
+	const w = index.wildcards[0];
+	if (w) return {
+		path: cleanPath,
+		params: {},
 		query,
 		hash,
-		matched: match.matched,
-		meta: mergeMeta(match.matched)
+		matched: w.matchedChain,
+		meta: w.meta
 	};
 	return {
 		path: cleanPath,
@@ -225,44 +445,6 @@ function resolveRoute(rawPath, routes) {
 		meta: {}
 	};
 }
-function matchRoutes(path, routes, parentMatched, parentParams = {}) {
-	for (const route of routes) {
-		const result = matchSingleRoute(path, route, parentMatched, parentParams);
-		if (result) return result;
-	}
-	return null;
-}
-function matchSingleRoute(path, route, parentMatched, parentParams) {
-	if (!route.children || route.children.length === 0) {
-		const params = matchPath(route.path, path);
-		if (params === null) return null;
-		return {
-			params: {
-				...parentParams,
-				...params
-			},
-			matched: [...parentMatched, route]
-		};
-	}
-	const prefix = matchPrefix(route.path, path);
-	if (prefix === null) return null;
-	const allParams = {
-		...parentParams,
-		...prefix.params
-	};
-	const matched = [...parentMatched, route];
-	const childMatch = matchRoutes(prefix.rest, route.children, matched, allParams);
-	if (childMatch) return childMatch;
-	const exactParams = matchPath(route.path, path);
-	if (exactParams === null) return null;
-	return {
-		params: {
-			...parentParams,
-			...exactParams
-		},
-		matched
-	};
-}
 /** Merge meta from matched routes (leaf takes precedence) */
 function mergeMeta(matched) {
 	const meta = {};
@@ -271,7 +453,11 @@ function mergeMeta(matched) {
 }
 /** Build a path string from a named route's pattern and params */
 function buildPath(pattern, params) {
-	return pattern.replace(/:([^/]+)\*?/g, (match, key) => {
+	return pattern.replace(/\/:([^/]+)\?/g, (_match, key) => {
+		const val = params[key];
+		if (!val) return "";
+		return `/${encodeURIComponent(val)}`;
+	}).replace(/:([^/]+)\*?/g, (match, key) => {
 		const val = params[key] ?? "";
 		if (match.endsWith("*")) return val.split("/").map(encodeURIComponent).join("/");
 		return encodeURIComponent(val);
@@ -393,28 +579,134 @@ function useRoute() {
 	if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
 	return router.currentRoute;
 }
+/**
+* In-component guard: called before the component's route is left.
+* Return `false` to cancel, a string to redirect, or `undefined`/`true` to proceed.
+* Automatically removed on component unmount.
+*
+* @example
+* onBeforeRouteLeave((to, from) => {
+*   if (hasUnsavedChanges()) return false
+* })
+*/
+function onBeforeRouteLeave(guard) {
+	const router = useContext(RouterContext) ?? _activeRouter;
+	if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
+	const currentMatched = router.currentRoute().matched;
+	const wrappedGuard = (to, from) => {
+		if (!from.matched.some((r) => currentMatched.includes(r))) return void 0;
+		return guard(to, from);
+	};
+	const remove = router.beforeEach(wrappedGuard);
+	onUnmount(() => remove());
+	return remove;
+}
+/**
+* In-component guard: called when the route changes but the component is reused
+* (e.g. `/user/1` → `/user/2`). Useful for reacting to param changes.
+* Automatically removed on component unmount.
+*
+* @example
+* onBeforeRouteUpdate((to, from) => {
+*   if (!isValidId(to.params.id)) return false
+* })
+*/
+function onBeforeRouteUpdate(guard) {
+	const router = useContext(RouterContext) ?? _activeRouter;
+	if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
+	const currentMatched = router.currentRoute().matched;
+	const wrappedGuard = (to, from) => {
+		if (!to.matched.some((r) => currentMatched.includes(r))) return void 0;
+		return guard(to, from);
+	};
+	const remove = router.beforeEach(wrappedGuard);
+	onUnmount(() => remove());
+	return remove;
+}
+/**
+* Register a navigation blocker. The `fn` callback is called before each
+* navigation — return `true` (or resolve to `true`) to block it.
+*
+* Automatically removed on component unmount if called during component setup.
+* Also installs a `beforeunload` handler so the browser shows a confirmation
+* dialog when the user tries to close the tab while a blocker is active.
+*
+* @example
+* const blocker = useBlocker((to, from) => {
+*   return hasUnsavedChanges() && !confirm("Discard changes?")
+* })
+* // later: blocker.remove()
+*/
+function useBlocker(fn) {
+	const router = useContext(RouterContext) ?? _activeRouter;
+	if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
+	router._blockers.add(fn);
+	const beforeUnloadHandler = _isBrowser ? (e) => {
+		e.preventDefault();
+	} : null;
+	if (beforeUnloadHandler) window.addEventListener("beforeunload", beforeUnloadHandler);
+	const remove = () => {
+		router._blockers.delete(fn);
+		if (beforeUnloadHandler) window.removeEventListener("beforeunload", beforeUnloadHandler);
+	};
+	onUnmount(() => remove());
+	return { remove };
+}
+/**
+* Reactive read/write access to the current route's query parameters.
+*
+* Returns `[get, set]` where `get` is a reactive signal producing the merged
+* query object and `set` navigates to the current path with updated params.
+*
+* @example
+* const [params, setParams] = useSearchParams({ page: "1", sort: "name" })
+* params().page  // "1" if not in URL
+* setParams({ page: "2" })  // navigates to ?page=2&sort=name
+*/
+function useSearchParams(defaults) {
+	const router = useContext(RouterContext) ?? _activeRouter;
+	if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
+	const get = () => {
+		const query = router.currentRoute().query;
+		if (!defaults) return query;
+		return {
+			...defaults,
+			...query
+		};
+	};
+	const set = (updates) => {
+		const merged = {
+			...get(),
+			...updates
+		};
+		const path = router.currentRoute().path + stringifyQuery(merged);
+		return router.replace(path);
+	};
+	return [get, set];
+}
 function createRouter(options) {
 	const opts = Array.isArray(options) ? { routes: options } : options;
-	const { routes, mode = "hash", scrollBehavior, onError, maxCacheSize = 100 } = opts;
+	const { routes, mode = "hash", scrollBehavior, onError, maxCacheSize = 100, trailingSlash = "strip" } = opts;
+	const base = mode === "history" ? normalizeBase(opts.base ?? "") : "";
 	const nameIndex = buildNameIndex(routes);
 	const guards = [];
 	const afterHooks = [];
 	const scrollManager = new ScrollManager(scrollBehavior);
 	let _navGen = 0;
 	const getInitialLocation = () => {
-		if (opts.url) return opts.url;
+		if (opts.url) return stripBase(opts.url, base);
 		if (!_isBrowser) return "/";
-		if (mode === "history") return window.location.pathname + window.location.search;
+		if (mode === "history") return stripBase(window.location.pathname, base) + window.location.search;
 		const hash = window.location.hash;
 		return hash.startsWith("#") ? hash.slice(1) || "/" : "/";
 	};
 	const getCurrentLocation = () => {
 		if (!_isBrowser) return currentPath();
-		if (mode === "history") return window.location.pathname + window.location.search;
+		if (mode === "history") return stripBase(window.location.pathname, base) + window.location.search;
 		const hash = window.location.hash;
 		return hash.startsWith("#") ? hash.slice(1) || "/" : "/";
 	};
-	const currentPath = signal(getInitialLocation());
+	const currentPath = signal(normalizeTrailingSlash(getInitialLocation(), trailingSlash));
 	const currentRoute = computed(() => resolveRoute(currentPath(), routes));
 	let _popstateHandler = null;
 	let _hashchangeHandler = null;
@@ -470,7 +762,7 @@ function createRouter(options) {
 	}
 	function syncBrowserUrl(path, replace) {
 		if (!_isBrowser) return;
-		const url = mode === "history" ? path : `#${path}`;
+		const url = mode === "history" ? `${base}${path}` : `#${path}`;
 		if (replace) window.history.replaceState(null, "", url);
 		else window.history.pushState(null, "", url);
 	}
@@ -486,27 +778,53 @@ function createRouter(options) {
 		if (enterOutcome.action !== "continue") return enterOutcome;
 		return runGlobalGuards(guards, to, from, gen);
 	}
-	async function runLoaders(to, gen, ac) {
-		const loadableRecords = to.matched.filter((r) => r.loader);
-		if (loadableRecords.length === 0) return true;
+	async function runBlockingLoaders(records, to, gen, ac) {
 		const loaderCtx = {
 			params: to.params,
 			query: to.query,
 			signal: ac.signal
 		};
-		const results = await Promise.allSettled(loadableRecords.map((r) => {
-			if (!r.loader) return Promise.resolve(void 0);
-			return r.loader(loaderCtx);
-		}));
+		const results = await Promise.allSettled(records.map((r) => r.loader ? r.loader(loaderCtx) : Promise.resolve(void 0)));
 		if (gen !== _navGen) return false;
-		for (let i = 0; i < loadableRecords.length; i++) {
+		for (let i = 0; i < records.length; i++) {
 			const result = results[i];
-			const record = loadableRecords[i];
+			const record = records[i];
 			if (!result || !record) continue;
 			if (!processLoaderResult(result, record, ac, to)) return false;
 		}
 		return true;
 	}
+	/** Fire-and-forget background revalidation for stale-while-revalidate routes. */
+	function revalidateSwrLoaders(records, to, ac) {
+		const loaderCtx = {
+			params: to.params,
+			query: to.query,
+			signal: ac.signal
+		};
+		for (const r of records) {
+			if (!r.loader) continue;
+			r.loader(loaderCtx).then((data) => {
+				if (!ac.signal.aborted) {
+					router._loaderData.set(r, data);
+					loadingSignal.update((n) => n + 1);
+					loadingSignal.update((n) => n - 1);
+				}
+			}).catch(() => {});
+		}
+	}
+	async function runLoaders(to, gen, ac) {
+		const loadableRecords = to.matched.filter((r) => r.loader);
+		if (loadableRecords.length === 0) return true;
+		const blocking = [];
+		const swr = [];
+		for (const r of loadableRecords) if (r.staleWhileRevalidate && router._loaderData.has(r)) swr.push(r);
+		else blocking.push(r);
+		if (blocking.length > 0) {
+			if (!await runBlockingLoaders(blocking, to, gen, ac)) return false;
+		}
+		if (swr.length > 0) revalidateSwrLoaders(swr, to, ac);
+		return true;
+	}
 	function commitNavigation(path, replace, to, from) {
 		scrollManager.save(from.path);
 		currentPath.set(path);
@@ -518,8 +836,16 @@ function createRouter(options) {
 		} catch (_err) {}
 		if (_isBrowser) queueMicrotask(() => scrollManager.restore(to, from));
 	}
-	async function navigate(path, replace, redirectDepth = 0) {
+	async function checkBlockers(to, from, gen) {
+		for (const blocker of router._blockers) {
+			const blocked = await blocker(to, from);
+			if (gen !== _navGen || blocked) return "cancel";
+		}
+		return "continue";
+	}
+	async function navigate(rawPath, replace, redirectDepth = 0) {
 		if (redirectDepth > 10) return;
+		const path = normalizeTrailingSlash(rawPath, trailingSlash);
 		const gen = ++_navGen;
 		loadingSignal.update((n) => n + 1);
 		const to = resolveRoute(path, routes);
@@ -529,6 +855,10 @@ function createRouter(options) {
 			loadingSignal.update((n) => n - 1);
 			return navigate(redirectTarget, replace, redirectDepth + 1);
 		}
+		if (await checkBlockers(to, from, gen) !== "continue") {
+			loadingSignal.update((n) => n - 1);
+			return;
+		}
 		const guardOutcome = await runAllGuards(to, from, gen);
 		if (guardOutcome.action !== "continue") {
 			loadingSignal.update((n) => n - 1);
@@ -545,9 +875,14 @@ function createRouter(options) {
 		commitNavigation(path, replace, to, from);
 		loadingSignal.update((n) => n - 1);
 	}
+	let _readyResolve = null;
+	const _readyPromise = new Promise((resolve) => {
+		_readyResolve = resolve;
+	});
 	const router = {
 		routes,
 		mode,
+		_base: base,
 		currentRoute,
 		_currentPath: currentPath,
 		_currentRoute: currentRoute,
@@ -559,18 +894,28 @@ function createRouter(options) {
 		_erroredChunks: /* @__PURE__ */ new Set(),
 		_loaderData: /* @__PURE__ */ new Map(),
 		_abortController: null,
+		_blockers: /* @__PURE__ */ new Set(),
+		_readyResolve,
+		_readyPromise,
 		_onError: onError,
 		_maxCacheSize: maxCacheSize,
 		async push(location) {
-			if (typeof location === "string") return navigate(sanitizePath(location), false);
+			if (typeof location === "string") return navigate(sanitizePath(resolveRelativePath(location, currentPath())), false);
 			return navigate(resolveNamedPath(location.name, location.params ?? {}, location.query ?? {}, nameIndex), false);
 		},
-		async replace(path) {
-			return navigate(sanitizePath(path), true);
+		async replace(location) {
+			if (typeof location === "string") return navigate(sanitizePath(resolveRelativePath(location, currentPath())), true);
+			return navigate(resolveNamedPath(location.name, location.params ?? {}, location.query ?? {}, nameIndex), true);
 		},
 		back() {
 			if (_isBrowser) window.history.back();
 		},
+		forward() {
+			if (_isBrowser) window.history.forward();
+		},
+		go(delta) {
+			if (_isBrowser) window.history.go(delta);
+		},
 		beforeEach(guard) {
 			guards.push(guard);
 			return () => {
@@ -586,6 +931,9 @@ function createRouter(options) {
 			};
 		},
 		loading: () => loadingSignal() > 0,
+		isReady() {
+			return router._readyPromise;
+		},
 		destroy() {
 			if (_popstateHandler) {
 				window.removeEventListener("popstate", _popstateHandler);
@@ -597,6 +945,7 @@ function createRouter(options) {
 			}
 			guards.length = 0;
 			afterHooks.length = 0;
+			router._blockers.clear();
 			componentCache.clear();
 			router._loaderData.clear();
 			router._abortController?.abort();
@@ -604,6 +953,12 @@ function createRouter(options) {
 		},
 		_resolve: (rawPath) => resolveRoute(rawPath, routes)
 	};
+	queueMicrotask(() => {
+		if (router._readyResolve) {
+			router._readyResolve();
+			router._readyResolve = null;
+		}
+	});
 	return router;
 }
 async function runGuard(guard, to, from) {
@@ -621,6 +976,45 @@ function resolveNamedPath(name, params, query, index) {
 	if (qs) path += `?${qs}`;
 	return path;
 }
+/** Normalize a base path: ensure leading `/`, strip trailing `/`. */
+function normalizeBase(raw) {
+	if (!raw) return "";
+	let b = raw;
+	if (!b.startsWith("/")) b = `/${b}`;
+	if (b.endsWith("/")) b = b.slice(0, -1);
+	return b;
+}
+/** Strip the base prefix from a full URL path. Returns the app-relative path. */
+function stripBase(path, base) {
+	if (!base) return path;
+	if (path === base || path === `${base}/`) return "/";
+	if (path.startsWith(`${base}/`)) return path.slice(base.length);
+	return path;
+}
+/** Normalize trailing slash on a path according to the configured strategy. */
+function normalizeTrailingSlash(path, strategy) {
+	if (strategy === "ignore" || path === "/") return path;
+	const qIdx = path.indexOf("?");
+	const hIdx = path.indexOf("#");
+	const endIdx = qIdx >= 0 ? qIdx : hIdx >= 0 ? hIdx : path.length;
+	const pathPart = path.slice(0, endIdx);
+	const suffix = path.slice(endIdx);
+	if (strategy === "strip") return pathPart.length > 1 && pathPart.endsWith("/") ? pathPart.slice(0, -1) + suffix : path;
+	return !pathPart.endsWith("/") ? `${pathPart}/${suffix}` : path;
+}
+/**
+* Resolve a relative path (starting with `.` or `..`) against the current path.
+* Non-relative paths are returned as-is.
+*/
+function resolveRelativePath(to, from) {
+	if (!to.startsWith("./") && !to.startsWith("../") && to !== "." && to !== "..") return to;
+	const fromSegments = from.split("/").filter(Boolean);
+	fromSegments.pop();
+	const toSegments = to.split("/").filter(Boolean);
+	for (const seg of toSegments) if (seg === "..") fromSegments.pop();
+	else if (seg !== ".") fromSegments.push(seg);
+	return `/${fromSegments.join("/")}`;
+}
 /** Block unsafe navigation targets: javascript/data/vbscript URIs and absolute URLs. */
 function sanitizePath(path) {
 	const trimmed = path.trim();
@@ -704,7 +1098,8 @@ const RouterLink = (props) => {
 		if (prefetchMode !== "hover" || !router) return;
 		prefetchRoute(router, props.to);
 	};
-	const href = router?.mode === "history" ? props.to : `#${props.to}`;
+	const inst = router;
+	const href = inst?.mode === "history" ? `${inst._base}${props.to}` : `#${props.to}`;
 	const activeClass = () => {
 		if (!router) return "";
 		const current = router.currentRoute().path;
@@ -826,5 +1221,5 @@ function isStaleChunk(err) {
 }
 
 //#endregion
-export { RouterContext, RouterLink, RouterProvider, RouterView, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useLoaderData, useRoute, useRouter };
+export { RouterContext, RouterLink, RouterProvider, RouterView, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useLoaderData, useRoute, useRouter, useSearchParams };
 //# sourceMappingURL=index.js.map