@pyreon/router 0.3.0 → 0.4.0

package/lib/types/index.d.ts

@@ -133,67 +133,256 @@ 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 */
+
+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));
+}
+/** 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("?");
@@ -203,14 +392,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: match.params,
+    params: {},
     query,
     hash,
-    matched: match.matched,
-    meta: mergeMeta(match.matched)
+    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: 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: w.matchedChain,
+    meta: w.meta
   };
   return {
     path: cleanPath,
@@ -221,44 +446,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 = {};
@@ -267,7 +454,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);
@@ -342,6 +533,113 @@ 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
@@ -351,27 +649,29 @@ function createRouter(options) {
     mode = "hash",
     scrollBehavior,
     onError,
-    maxCacheSize = 100
+    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;
@@ -437,7 +737,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);
   }
   function resolveRedirect(to) {
@@ -452,27 +752,52 @@ 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);
@@ -484,8 +809,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);
@@ -495,6 +828,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);
@@ -511,9 +848,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,
@@ -525,18 +867,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 () => {
@@ -552,6 +904,9 @@ function createRouter(options) {
       };
     },
     loading: () => loadingSignal() > 0,
+    isReady() {
+      return router._readyPromise;
+    },
     destroy() {
       if (_popstateHandler) {
         window.removeEventListener("popstate", _popstateHandler);
@@ -563,6 +918,7 @@ function createRouter(options) {
       }
       guards.length = 0;
       afterHooks.length = 0;
+      router._blockers.clear();
       componentCache.clear();
       router._loaderData.clear();
       router._abortController?.abort();
@@ -570,6 +926,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) {
@@ -587,6 +949,44 @@ 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();
@@ -686,5 +1086,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.d.ts.map