@pyreon/router 0.5.6 → 0.5.7

package/lib/types/index.d.ts

@@ -1,1090 +1,435 @@
-import { createContext, createRef, h, onUnmount, popContext, pushContext, useContext } from "@pyreon/core";
-import { computed, signal } from "@pyreon/reactivity";
+import * as _pyreon_core0 from "@pyreon/core";
+import { ComponentFn, ComponentFn as ComponentFn$1, Props, VNode, VNodeChild } from "@pyreon/core";
+import { Computed, Signal } from "@pyreon/reactivity";
 
-//#region src/loader.ts
+//#region src/types.d.ts
 /**
-* Context frame that holds the loader data for the currently rendered route record.
-* Pushed by RouterView's withLoaderData wrapper before invoking the route component.
-*/
-
-/**
-* Returns the data resolved by the current route's `loader` function.
-* Must be called inside a route component rendered by <RouterView />.
-*
-* @example
-* const routes = [{ path: "/users", component: Users, loader: fetchUsers }]
-*
-* function Users() {
-*   const users = useLoaderData<User[]>()
-*   return h("ul", null, users.map(u => h("li", null, u.name)))
-* }
-*/
-function useLoaderData() {
-  return useContext(LoaderDataContext);
-}
-/**
-* SSR helper: pre-run all loaders for the given path before rendering.
-* Call this before `renderToString` so route components can read data via `useLoaderData()`.
-*
-* @example
-* const router = createRouter({ routes, url: req.url })
-* await prefetchLoaderData(router, req.url)
-* const html = await renderToString(h(App, { router }))
-*/
-async function prefetchLoaderData(router, path) {
-  const route = router._resolve(path);
-  const ac = new AbortController();
-  router._abortController = ac;
-  await Promise.all(route.matched.filter(r => r.loader).map(async r => {
-    const data = await r.loader?.({
-      params: route.params,
-      query: route.query,
-      signal: ac.signal
-    });
-    router._loaderData.set(r, data);
-  }));
-}
+ * Extracts typed params from a path string at compile time.
+ * Supports optional params via `:param?` — their type is `string | undefined`.
+ *
+ * @example
+ * ExtractParams<'/user/:id/posts/:postId'>
+ * // → { id: string; postId: string }
+ *
+ * ExtractParams<'/user/:id?'>
+ * // → { id?: string | undefined }
+ */
+type ExtractParams<T extends string> = T extends `${string}:${infer Param}*/${infer Rest}` ? { [K in Param]: string } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}*` ? { [K in Param]: string } : T extends `${string}:${infer Param}?/${infer Rest}` ? { [K in Param]?: string | undefined } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}?` ? { [K in Param]?: string | undefined } : T extends `${string}:${infer Param}/${infer Rest}` ? { [K in Param]: string } & ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}` ? { [K in Param]: string } : Record<never, never>;
 /**
-* Serialize loader data to a JSON-safe plain object for embedding in SSR HTML.
-* Keys are route path patterns (stable across server and client).
-*
-* @example — SSR handler:
-* await prefetchLoaderData(router, req.url)
-* const { html, head } = await renderWithHead(h(App, null))
-* const page = `...${head}
-*   <script>window.__PYREON_LOADER_DATA__=${JSON.stringify(serializeLoaderData(router))}<\/script>
-*   ...${html}...`
-*/
-function serializeLoaderData(router) {
-  const result = {};
-  for (const [record, data] of router._loaderData) result[record.path] = data;
-  return result;
-}
+ * Route metadata interface. Extend it via module augmentation to add custom fields:
+ *
+ * @example
+ * // globals.d.ts
+ * declare module "@pyreon/router" {
+ *   interface RouteMeta {
+ *     requiresRole?: "admin" | "user"
+ *     pageTitle?: string
+ *   }
+ * }
+ */
+interface RouteMeta {
+  /** Sets document.title on navigation */
+  title?: string;
+  /** Page description (for meta tags) */
+  description?: string;
+  /** If true, guards can redirect to login */
+  requiresAuth?: boolean;
+  /** Scroll behavior for this route */
+  scrollBehavior?: "top" | "restore" | "none";
+}
+interface ResolvedRoute<P extends Record<string, string | undefined> = Record<string, string>, Q extends Record<string, string> = Record<string, string>> {
+  path: string;
+  params: P;
+  query: Q;
+  hash: string;
+  /** All matched records from root to leaf (one per nesting level) */
+  matched: RouteRecord[];
+  meta: RouteMeta;
+}
+declare const LAZY_SYMBOL: unique symbol;
+interface LazyComponent {
+  readonly [LAZY_SYMBOL]: true;
+  readonly loader: () => Promise<ComponentFn$1 | {
+    default: ComponentFn$1;
+  }>;
+  /** Optional component shown while the lazy chunk is loading */
+  readonly loadingComponent?: ComponentFn$1;
+  /** Optional component shown after all retries have failed */
+  readonly errorComponent?: ComponentFn$1;
+}
+declare function lazy(loader: () => Promise<ComponentFn$1 | {
+  default: ComponentFn$1;
+}>, options?: {
+  loading?: ComponentFn$1;
+  error?: ComponentFn$1;
+}): LazyComponent;
+type RouteComponent = ComponentFn$1 | LazyComponent;
+type NavigationGuardResult = boolean | string | undefined;
+type NavigationGuard = (to: ResolvedRoute, from: ResolvedRoute) => NavigationGuardResult | Promise<NavigationGuardResult>;
+type AfterEachHook = (to: ResolvedRoute, from: ResolvedRoute) => void;
 /**
-* Hydrate loader data from a serialized object (e.g. `window.__PYREON_LOADER_DATA__`).
-* Populates the router's internal `_loaderData` map so the initial render uses
-* server-fetched data without re-running loaders on the client.
-*
-* Call this before `mount()`, after `createRouter()`.
-*
-* @example — client entry:
-* import { hydrateLoaderData } from "@pyreon/router"
-* const router = createRouter({ routes })
-* hydrateLoaderData(router, window.__PYREON_LOADER_DATA__ ?? {})
-* mount(h(App, null), document.getElementById("app")!)
-*/
-function hydrateLoaderData(router, serialized) {
-  if (!serialized || typeof serialized !== "object") return;
-  const route = router._resolve(router.currentRoute().path);
-  for (const record of route.matched) if (Object.hasOwn(serialized, record.path)) router._loaderData.set(record, serialized[record.path]);
+ * Called before each navigation. Return `true` to block, `false` to allow.
+ * Async blockers are supported (e.g. to show a confirmation dialog).
+ */
+type BlockerFn = (to: ResolvedRoute, from: ResolvedRoute) => boolean | Promise<boolean>;
+interface Blocker {
+  /** Unregister this blocker so future navigations proceed freely. */
+  remove(): void;
+}
+interface LoaderContext {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  /** Aborted when a newer navigation supersedes this one */
+  signal: AbortSignal;
+}
+type RouteLoaderFn = (ctx: LoaderContext) => Promise<unknown>;
+interface RouteRecord<TPath extends string = string> {
+  /** Path pattern — supports `:param` segments and `(.*)` wildcard */
+  path: TPath;
+  component: RouteComponent;
+  /** Optional route name for named navigation */
+  name?: string;
+  /** Metadata attached to this route */
+  meta?: RouteMeta;
+  /**
+   * Redirect target. Evaluated before guards.
+   * String: redirect to that path.
+   * Function: called with the resolved route, return path string.
+   */
+  redirect?: string | ((to: ResolvedRoute) => string);
+  /** Guard(s) run only for this route, before global beforeEach guards */
+  beforeEnter?: NavigationGuard | NavigationGuard[];
+  /** Guard(s) run before leaving this route. Return false to cancel. */
+  beforeLeave?: NavigationGuard | NavigationGuard[];
+  /**
+   * Alternative path(s) for this route. Alias paths render the same component
+   * and share guards, loaders, and metadata with the primary path.
+   *
+   * @example
+   * { path: "/user/:id", alias: ["/profile/:id"], component: UserPage }
+   */
+  alias?: string | string[];
+  /** Child routes rendered inside this route's component via <RouterView /> */
+  children?: RouteRecord[];
+  /**
+   * Data loader — runs before navigation commits, in parallel with sibling loaders.
+   * The result is accessible via `useLoaderData()` inside the route component.
+   * Receives an AbortSignal that fires if a newer navigation supersedes this one.
+   */
+  loader?: RouteLoaderFn;
+  /**
+   * When true, the router shows cached loader data immediately (stale) and
+   * revalidates in the background. The component re-renders once fresh data arrives.
+   * Only applies when navigating to a route that already has cached loader data.
+   */
+  staleWhileRevalidate?: boolean;
+  /** Component rendered when this route's loader throws an error */
+  errorComponent?: ComponentFn$1;
+}
+type ScrollBehaviorFn = (to: ResolvedRoute, from: ResolvedRoute, savedPosition: number | null) => "top" | "restore" | "none" | number;
+interface RouterOptions {
+  routes: RouteRecord[];
+  /** "hash" (default) uses location.hash; "history" uses pushState */
+  mode?: "hash" | "history";
+  /**
+   * Base path for the application. Used when deploying to a sub-path
+   * (e.g. `"/app"` for `https://example.com/app/`).
+   * Only applies in history mode. Must start with `/`.
+   * Default: `""` (no base path).
+   */
+  base?: string;
+  /**
+   * Global scroll behavior. Per-route meta.scrollBehavior takes precedence.
+   * Default: "top"
+   */
+  scrollBehavior?: ScrollBehaviorFn | "top" | "restore" | "none";
+  /**
+   * Initial URL for SSR. On the server, window.location is unavailable;
+   * pass the request URL here so the router resolves the correct route.
+   *
+   * @example
+   * // In your SSR handler:
+   * const router = createRouter({ routes, url: req.url })
+   */
+  url?: string;
+  /**
+   * Called when a route loader throws. If not provided, errors are logged
+   * and the navigation continues with `undefined` data for the failed loader.
+   * Return `false` to cancel the navigation.
+   */
+  onError?: (err: unknown, route: ResolvedRoute) => undefined | false;
+  /**
+   * Maximum number of resolved lazy components to cache.
+   * When exceeded, the oldest entry is evicted.
+   * Default: 100.
+   */
+  maxCacheSize?: number;
+  /**
+   * Trailing slash handling:
+   *   - `"strip"` — removes trailing slashes before matching (default)
+   *   - `"add"` — ensures paths always end with `/`
+   *   - `"ignore"` — no normalization
+   */
+  trailingSlash?: "strip" | "add" | "ignore";
+}
+interface Router {
+  /** Navigate to a path */
+  push(path: string): Promise<void>;
+  /** Navigate to a path by name */
+  push(location: {
+    name: string;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+  }): Promise<void>;
+  /** Replace current history entry */
+  replace(path: string): Promise<void>;
+  /** Replace current history entry using a named route */
+  replace(location: {
+    name: string;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+  }): Promise<void>;
+  /** Go back one step in history */
+  back(): void;
+  /** Go forward one step in history */
+  forward(): void;
+  /** Navigate forward or backward by `delta` steps in the history stack */
+  go(delta: number): void;
+  /** Register a global before-navigation guard. Returns an unregister function. */
+  beforeEach(guard: NavigationGuard): () => void;
+  /** Register a global after-navigation hook. Returns an unregister function. */
+  afterEach(hook: AfterEachHook): () => void;
+  /** Current resolved route (reactive signal) */
+  readonly currentRoute: () => ResolvedRoute;
+  /** True while a navigation (guards + loaders) is in flight */
+  readonly loading: () => boolean;
+  /**
+   * Promise that resolves once the initial navigation is complete.
+   * Useful for SSR and for delaying rendering until the first route is resolved.
+   */
+  isReady(): Promise<void>;
+  /** Remove all event listeners, clear caches, and abort in-flight navigations. */
+  destroy(): void;
+}
+interface RouterInstance extends Router {
+  routes: RouteRecord[];
+  mode: "hash" | "history";
+  /** Normalized base path (e.g. "/app"), empty string if none */
+  _base: string;
+  _currentPath: Signal<string>;
+  _currentRoute: Computed<ResolvedRoute>;
+  _componentCache: Map<RouteRecord, ComponentFn$1>;
+  _loadingSignal: Signal<number>;
+  _resolve(rawPath: string): ResolvedRoute;
+  _scrollPositions: Map<string, number>;
+  _scrollBehavior: RouterOptions["scrollBehavior"];
+  _onError: RouterOptions["onError"];
+  _maxCacheSize: number;
+  /**
+   * Current RouterView nesting depth. Incremented by each RouterView as it
+   * mounts (in tree order = depth-first), so each view knows which level of
+   * `matched[]` to render. Reset to 0 by RouterProvider.
+   */
+  _viewDepth: number;
+  /** Route records whose lazy chunk permanently failed (all retries exhausted) */
+  _erroredChunks: Set<RouteRecord>;
+  /** Loader data keyed by route record — populated before each navigation commits */
+  _loaderData: Map<RouteRecord, unknown>;
+  /** AbortController for the in-flight loader batch — aborted when a newer navigation starts */
+  _abortController: AbortController | null;
+  /** Registered navigation blockers */
+  _blockers: Set<BlockerFn>;
+  /** Resolves the isReady() promise after initial navigation completes */
+  _readyResolve: (() => void) | null;
+  /** The isReady() promise instance */
+  _readyPromise: Promise<void>;
 }
-
 //#endregion
-//#region src/match.ts
-/**
-* Parse a query string into key-value pairs. Duplicate keys are overwritten
-* (last value wins). Use `parseQueryMulti` to preserve duplicates as arrays.
-*/
-function parseQuery(qs) {
-  if (!qs) return {};
-  const result = {};
-  for (const part of qs.split("&")) {
-    const eqIdx = part.indexOf("=");
-    if (eqIdx < 0) {
-      const key = decodeURIComponent(part);
-      if (key) result[key] = "";
-    } else {
-      const key = decodeURIComponent(part.slice(0, eqIdx));
-      const val = decodeURIComponent(part.slice(eqIdx + 1));
-      if (key) result[key] = val;
-    }
-  }
-  return result;
-}
-/**
-* Parse a query string preserving duplicate keys as arrays.
-*
-* @example
-* parseQueryMulti("color=red&color=blue&size=lg")
-* // → { color: ["red", "blue"], size: "lg" }
-*/
-function parseQueryMulti(qs) {
-  if (!qs) return {};
-  const result = {};
-  for (const part of qs.split("&")) {
-    const eqIdx = part.indexOf("=");
-    let key;
-    let val;
-    if (eqIdx < 0) {
-      key = decodeURIComponent(part);
-      val = "";
-    } else {
-      key = decodeURIComponent(part.slice(0, eqIdx));
-      val = decodeURIComponent(part.slice(eqIdx + 1));
-    }
-    if (!key) continue;
-    const existing = result[key];
-    if (existing === void 0) result[key] = val;else if (Array.isArray(existing)) existing.push(val);else result[key] = [existing, val];
-  }
-  return result;
+//#region src/components.d.ts
+interface RouterProviderProps extends Props {
+  router: Router;
+  children?: VNode | VNodeChild | null;
 }
-function stringifyQuery(query) {
-  const parts = [];
-  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
-  };
+declare const RouterProvider: ComponentFn<RouterProviderProps>;
+interface RouterViewProps extends Props {
+  /** Explicitly pass a router (optional — uses the active router by default) */
+  router?: Router;
 }
 /**
-* Flatten nested routes into leaf entries with pre-joined segments.
-* This eliminates recursion during matching for the common case.
-*/
-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 = {};
-  const segments = f.segments;
-  const count = f.segmentCount;
-  for (let i = 0; i < count; i++) {
-    const seg = segments[i];
-    const pt = pathParts[i];
-    if (!seg) return null;
-    if (seg.isSplat) {
-      params[seg.paramName] = captureSplat(pathParts, i, pathLen);
-      return params;
-    }
-    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;
-  }
-  return params;
-}
-/** 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 null;
-}
-/**
-* Resolve a raw path (including query string and hash) against the route tree.
-* Uses flattened index for O(1) static lookup and first-segment dispatch.
-*/
-function resolveRoute(rawPath, routes) {
-  const qIdx = rawPath.indexOf("?");
-  const pathAndHash = qIdx >= 0 ? rawPath.slice(0, qIdx) : rawPath;
-  const queryPart = qIdx >= 0 ? rawPath.slice(qIdx + 1) : "";
-  const hIdx = pathAndHash.indexOf("#");
-  const cleanPath = hIdx >= 0 ? pathAndHash.slice(0, hIdx) : pathAndHash;
-  const hash = hIdx >= 0 ? pathAndHash.slice(hIdx + 1) : "";
-  const query = parseQuery(queryPart);
-  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: 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,
-    params: {},
-    query,
-    hash,
-    matched: [],
-    meta: {}
-  };
-}
-/** Merge meta from matched routes (leaf takes precedence) */
-function mergeMeta(matched) {
-  const meta = {};
-  for (const record of matched) if (record.meta) Object.assign(meta, record.meta);
-  return meta;
-}
-/** Build a path string from a named route's pattern and params */
-function buildPath(pattern, params) {
-  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);
-  });
-}
-/** Find a route record by name (recursive, O(n)). Prefer buildNameIndex for repeated lookups. */
-function findRouteByName(name, routes) {
-  for (const route of routes) {
-    if (route.name === name) return route;
-    if (route.children) {
-      const found = findRouteByName(name, route.children);
-      if (found) return found;
-    }
-  }
-  return null;
-}
-/**
-* Pre-build a name → RouteRecord index from a route tree for O(1) named navigation.
-* Called once at router creation time; avoids O(n) depth-first search per push({ name }).
-*/
-function buildNameIndex(routes) {
-  const index = /* @__PURE__ */new Map();
-  function walk(list) {
-    for (const route of list) {
-      if (route.name) index.set(route.name, route);
-      if (route.children) walk(route.children);
-    }
-  }
-  walk(routes);
-  return index;
-}
-
+ * Renders the matched route component at this nesting level.
+ *
+ * Nested layouts work by placing a second `<RouterView />` inside the layout
+ * component — it automatically renders the next level of the matched route.
+ *
+ * How depth tracking works:
+ * Pyreon components run once in depth-first tree order. Each `RouterView`
+ * captures `router._viewDepth` at setup time and immediately increments it,
+ * so sibling and child views get the correct index. `onUnmount` decrements
+ * the counter so dynamic route swaps work correctly.
+ *
+ * @example
+ * // Route config:
+ * { path: "/admin", component: AdminLayout, children: [
+ *   { path: "users", component: AdminUsers },
+ * ]}
+ *
+ * // AdminLayout renders a nested RouterView:
+ * function AdminLayout() {
+ *   return <div><Sidebar /><RouterView /></div>
+ * }
+ */
+declare const RouterView: ComponentFn<RouterViewProps>;
+interface RouterLinkProps extends Props {
+  to: string;
+  /** If true, uses router.replace() instead of router.push() */
+  replace?: boolean;
+  /** CSS class applied when this link is active (default: "router-link-active") */
+  activeClass?: string;
+  /** CSS class for exact-match active state (default: "router-link-exact-active") */
+  exactActiveClass?: string;
+  /** If true, only applies activeClass on exact match */
+  exact?: boolean;
+  /**
+   * Prefetch strategy for loader data:
+   *   - "hover" (default) — prefetch when the user hovers over the link
+   *   - "viewport" — prefetch when the link scrolls into the viewport
+   *   - "none" — no prefetching
+   */
+  prefetch?: "hover" | "viewport" | "none";
+  children?: VNodeChild | null;
+}
+declare const RouterLink: ComponentFn<RouterLinkProps>;
 //#endregion
-//#region src/scroll.ts
+//#region src/loader.d.ts
 /**
-* Scroll restoration manager.
-*
-* Saves scroll position before each navigation and restores it when
-* navigating back to a previously visited path.
-*/
-
-function lazy(loader, options) {
-  return {
-    [LAZY_SYMBOL]: true,
-    loader,
-    ...(options?.loading ? {
-      loadingComponent: options.loading
-    } : {}),
-    ...(options?.error ? {
-      errorComponent: options.error
-    } : {})
-  };
-}
-function isLazy(c) {
-  return typeof c === "object" && c !== null && c[LAZY_SYMBOL] === true;
-}
-
-//#endregion
-//#region src/router.ts
-
-function setActiveRouter(router) {
-  if (router) router._viewDepth = 0;
-  _activeRouter = router;
-}
-function useRouter() {
-  const router = useContext(RouterContext) ?? _activeRouter;
-  if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
-  return router;
-}
-function useRoute() {
-  const router = useContext(RouterContext) ?? _activeRouter;
-  if (!router) throw new Error("[pyreon-router] No router installed. Wrap your app in <RouterProvider router={router}>.");
-  return router.currentRoute;
-}
+ * Returns the data resolved by the current route's `loader` function.
+ * Must be called inside a route component rendered by <RouterView />.
+ *
+ * @example
+ * const routes = [{ path: "/users", component: Users, loader: fetchUsers }]
+ *
+ * function Users() {
+ *   const users = useLoaderData<User[]>()
+ *   return h("ul", null, users.map(u => h("li", null, u.name)))
+ * }
+ */
+declare function useLoaderData<T = unknown>(): T;
 /**
-* 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;
-}
+ * SSR helper: pre-run all loaders for the given path before rendering.
+ * Call this before `renderToString` so route components can read data via `useLoaderData()`.
+ *
+ * @example
+ * const router = createRouter({ routes, url: req.url })
+ * await prefetchLoaderData(router, req.url)
+ * const html = await renderToString(h(App, { router }))
+ */
+declare function prefetchLoaderData(router: RouterInstance, path: string): Promise<void>;
 /**
-* 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;
-}
+ * Serialize loader data to a JSON-safe plain object for embedding in SSR HTML.
+ * Keys are route path patterns (stable across server and client).
+ *
+ * @example — SSR handler:
+ * await prefetchLoaderData(router, req.url)
+ * const { html, head } = await renderWithHead(h(App, null))
+ * const page = `...${head}
+ *   <script>window.__PYREON_LOADER_DATA__=${JSON.stringify(serializeLoaderData(router))}</script>
+ *   ...${html}...`
+ */
+declare function serializeLoaderData(router: RouterInstance): Record<string, unknown>;
 /**
-* 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
-  };
-}
+ * Hydrate loader data from a serialized object (e.g. `window.__PYREON_LOADER_DATA__`).
+ * Populates the router's internal `_loaderData` map so the initial render uses
+ * server-fetched data without re-running loaders on the client.
+ *
+ * Call this before `mount()`, after `createRouter()`.
+ *
+ * @example — client entry:
+ * import { hydrateLoaderData } from "@pyreon/router"
+ * const router = createRouter({ routes })
+ * hydrateLoaderData(router, window.__PYREON_LOADER_DATA__ ?? {})
+ * mount(h(App, null), document.getElementById("app")!)
+ */
+declare function hydrateLoaderData(router: RouterInstance, serialized: Record<string, unknown>): void;
+//#endregion
+//#region src/match.d.ts
 /**
-* 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,
-    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 stripBase(opts.url, base);
-    if (!_isBrowser) return "/";
-    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 stripBase(window.location.pathname, base) + window.location.search;
-    const hash = window.location.hash;
-    return hash.startsWith("#") ? hash.slice(1) || "/" : "/";
-  };
-  const currentPath = signal(normalizeTrailingSlash(getInitialLocation(), trailingSlash));
-  const currentRoute = computed(() => resolveRoute(currentPath(), routes));
-  let _popstateHandler = null;
-  let _hashchangeHandler = null;
-  if (_isBrowser) if (mode === "history") {
-    _popstateHandler = () => currentPath.set(getCurrentLocation());
-    window.addEventListener("popstate", _popstateHandler);
-  } else {
-    _hashchangeHandler = () => currentPath.set(getCurrentLocation());
-    window.addEventListener("hashchange", _hashchangeHandler);
-  }
-  const componentCache = /* @__PURE__ */new Map();
-  const loadingSignal = signal(0);
-  async function evaluateGuard(guard, to, from, gen) {
-    const result = await runGuard(guard, to, from);
-    if (gen !== _navGen) return {
-      action: "cancel"
-    };
-    if (result === false) return {
-      action: "cancel"
-    };
-    if (typeof result === "string") return {
-      action: "redirect",
-      target: result
-    };
-    return {
-      action: "continue"
-    };
-  }
-  async function runRouteGuards(records, guardKey, to, from, gen) {
-    for (const record of records) {
-      const raw = record[guardKey];
-      if (!raw) continue;
-      const routeGuards = Array.isArray(raw) ? raw : [raw];
-      for (const guard of routeGuards) {
-        const outcome = await evaluateGuard(guard, to, from, gen);
-        if (outcome.action !== "continue") return outcome;
-      }
-    }
-    return {
-      action: "continue"
-    };
-  }
-  async function runGlobalGuards(globalGuards, to, from, gen) {
-    for (const guard of globalGuards) {
-      const outcome = await evaluateGuard(guard, to, from, gen);
-      if (outcome.action !== "continue") return outcome;
-    }
-    return {
-      action: "continue"
-    };
-  }
-  function processLoaderResult(result, record, ac, to) {
-    if (result.status === "fulfilled") {
-      router._loaderData.set(record, result.value);
-      return true;
-    }
-    if (ac.signal.aborted) return true;
-    if (router._onError) {
-      if (router._onError(result.reason, to) === false) return false;
-    }
-    router._loaderData.set(record, void 0);
-    return true;
-  }
-  function syncBrowserUrl(path, replace) {
-    if (!_isBrowser) return;
-    const url = mode === "history" ? `${base}${path}` : `#${path}`;
-    if (replace) window.history.replaceState(null, "", url);else window.history.pushState(null, "", url);
-  }
-  function resolveRedirect(to) {
-    const leaf = to.matched[to.matched.length - 1];
-    if (!leaf?.redirect) return null;
-    return sanitizePath(typeof leaf.redirect === "function" ? leaf.redirect(to) : leaf.redirect);
-  }
-  async function runAllGuards(to, from, gen) {
-    const leaveOutcome = await runRouteGuards(from.matched, "beforeLeave", to, from, gen);
-    if (leaveOutcome.action !== "continue") return leaveOutcome;
-    const enterOutcome = await runRouteGuards(to.matched, "beforeEnter", to, from, gen);
-    if (enterOutcome.action !== "continue") return enterOutcome;
-    return runGlobalGuards(guards, to, from, gen);
-  }
-  async function runBlockingLoaders(records, to, gen, ac) {
-    const loaderCtx = {
-      params: to.params,
-      query: to.query,
-      signal: ac.signal
-    };
-    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 < records.length; i++) {
-      const result = results[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);
-    syncBrowserUrl(path, replace);
-    if (_isBrowser && to.meta.title) document.title = to.meta.title;
-    for (const record of router._loaderData.keys()) if (!to.matched.includes(record)) router._loaderData.delete(record);
-    for (const hook of afterHooks) try {
-      hook(to, from);
-    } catch (_err) {}
-    if (_isBrowser) queueMicrotask(() => scrollManager.restore(to, from));
-  }
-  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);
-    const from = currentRoute();
-    const redirectTarget = resolveRedirect(to);
-    if (redirectTarget !== null) {
-      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);
-      if (guardOutcome.action === "redirect") return navigate(sanitizePath(guardOutcome.target), replace, redirectDepth + 1);
-      return;
-    }
-    router._abortController?.abort();
-    const ac = new AbortController();
-    router._abortController = ac;
-    if (!(await runLoaders(to, gen, ac))) {
-      loadingSignal.update(n => n - 1);
-      return;
-    }
-    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,
-    _componentCache: componentCache,
-    _loadingSignal: loadingSignal,
-    _scrollPositions: /* @__PURE__ */new Map(),
-    _scrollBehavior: scrollBehavior,
-    _viewDepth: 0,
-    _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(resolveRelativePath(location, currentPath())), false);
-      return navigate(resolveNamedPath(location.name, location.params ?? {}, location.query ?? {}, nameIndex), false);
-    },
-    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 () => {
-        const idx = guards.indexOf(guard);
-        if (idx >= 0) guards.splice(idx, 1);
-      };
-    },
-    afterEach(hook) {
-      afterHooks.push(hook);
-      return () => {
-        const idx = afterHooks.indexOf(hook);
-        if (idx >= 0) afterHooks.splice(idx, 1);
-      };
-    },
-    loading: () => loadingSignal() > 0,
-    isReady() {
-      return router._readyPromise;
-    },
-    destroy() {
-      if (_popstateHandler) {
-        window.removeEventListener("popstate", _popstateHandler);
-        _popstateHandler = null;
-      }
-      if (_hashchangeHandler) {
-        window.removeEventListener("hashchange", _hashchangeHandler);
-        _hashchangeHandler = null;
-      }
-      guards.length = 0;
-      afterHooks.length = 0;
-      router._blockers.clear();
-      componentCache.clear();
-      router._loaderData.clear();
-      router._abortController?.abort();
-      router._abortController = null;
-    },
-    _resolve: rawPath => resolveRoute(rawPath, routes)
-  };
-  queueMicrotask(() => {
-    if (router._readyResolve) {
-      router._readyResolve();
-      router._readyResolve = null;
-    }
-  });
-  return router;
-}
-async function runGuard(guard, to, from) {
-  try {
-    return await guard(to, from);
-  } catch (_err) {
-    return false;
-  }
-}
-function resolveNamedPath(name, params, query, index) {
-  const record = index.get(name);
-  if (!record) return "/";
-  let path = buildPath(record.path, params);
-  const qs = Object.entries(query).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
-  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;
-}
+ * Parse a query string into key-value pairs. Duplicate keys are overwritten
+ * (last value wins). Use `parseQueryMulti` to preserve duplicates as arrays.
+ */
+declare function parseQuery(qs: string): Record<string, string>;
 /**
-* 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();
-  if (/^(?:javascript|data|vbscript):/i.test(trimmed)) return "/";
-  if (/^\/\/|^https?:/i.test(trimmed)) return "/";
-  return path;
-}
-
+ * Parse a query string preserving duplicate keys as arrays.
+ *
+ * @example
+ * parseQueryMulti("color=red&color=blue&size=lg")
+ * // → { color: ["red", "blue"], size: "lg" }
+ */
+declare function parseQueryMulti(qs: string): Record<string, string | string[]>;
+declare function stringifyQuery(query: Record<string, string>): string;
+/**
+ * Resolve a raw path (including query string and hash) against the route tree.
+ * Uses flattened index for O(1) static lookup and first-segment dispatch.
+ */
+declare function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRoute;
+/** Build a path string from a named route's pattern and params */
+declare function buildPath(pattern: string, params: Record<string, string>): string;
+/** Find a route record by name (recursive, O(n)). Prefer buildNameIndex for repeated lookups. */
+declare function findRouteByName(name: string, routes: RouteRecord[]): RouteRecord | null;
 //#endregion
-//#region src/components.tsx
-
-/** Prefetch loader data for a route (only once per router + path). */
-function prefetchRoute(router, path) {
-  let set = _prefetched.get(router);
-  if (!set) {
-    set = /* @__PURE__ */new Set();
-    _prefetched.set(router, set);
-  }
-  if (set.has(path)) return;
-  set.add(path);
-  prefetchLoaderData(router, path).catch(() => {
-    set?.delete(path);
-  });
-}
-function renderLazyRoute(router, record, raw) {
-  if (router._erroredChunks.has(record)) return raw.errorComponent ? h(raw.errorComponent, {}) : null;
-  const tryLoad = attempt => raw.loader().then(mod => {
-    cacheSet(router, record, typeof mod === "function" ? mod : mod.default);
-    router._loadingSignal.update(n => n + 1);
-  }).catch(err => {
-    if (attempt < 3) return new Promise(res => setTimeout(res, 500 * 2 ** attempt)).then(() => tryLoad(attempt + 1));
-    if (typeof window !== "undefined" && isStaleChunk(err)) {
-      window.location.reload();
-      return;
-    }
-    router._erroredChunks.add(record);
-    router._loadingSignal.update(n => n + 1);
-  });
-  tryLoad(0);
-  return raw.loadingComponent ? h(raw.loadingComponent, {}) : null;
-}
+//#region src/router.d.ts
+declare const RouterContext: _pyreon_core0.Context<RouterInstance | null>;
+declare function useRouter(): Router;
+declare function useRoute<TPath extends string = string>(): () => ResolvedRoute<ExtractParams<TPath> & Record<string, string>, Record<string, string>>;
 /**
-* Wraps the route component with a LoaderDataProvider so `useLoaderData()` works
-* inside the component. If the record has no loader, renders the component directly.
-*/
-function renderWithLoader(router, record, Comp, route) {
-  const routeProps = {
-    params: route.params,
-    query: route.query,
-    meta: route.meta
-  };
-  if (!record.loader) return h(Comp, routeProps);
-  const data = router._loaderData.get(record);
-  if (data === void 0 && record.errorComponent) return h(record.errorComponent, routeProps);
-  return h(LoaderDataProvider, {
-    data,
-    children: h(Comp, routeProps)
-  });
-}
+ * 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
+ * })
+ */
+declare function onBeforeRouteLeave(guard: NavigationGuard): () => void;
 /**
-* Thin provider component that pushes LoaderDataContext before children mount.
-* Uses Pyreon's context stack so useLoaderData() reads it during child setup.
-*/
-function LoaderDataProvider(props) {
-  pushContext(new Map([[LoaderDataContext.id, props.data]]));
-  onUnmount(() => popContext());
-  return props.children;
-}
-/** Evict oldest cache entries when the component cache exceeds maxCacheSize. */
-function cacheSet(router, record, comp) {
-  router._componentCache.set(record, comp);
-  if (router._componentCache.size > router._maxCacheSize) {
-    const oldest = router._componentCache.keys().next().value;
-    router._componentCache.delete(oldest);
-  }
-}
+ * 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
+ * })
+ */
+declare function onBeforeRouteUpdate(guard: NavigationGuard): () => void;
 /**
-* Segment-aware prefix check for active link matching.
-* `/admin` is a prefix of `/admin/users` but NOT of `/admin-panel`.
-*/
-function isSegmentPrefix(current, target) {
-  if (target === "/") return false;
-  const cs = current.split("/").filter(Boolean);
-  const ts = target.split("/").filter(Boolean);
-  if (ts.length > cs.length) return false;
-  return ts.every((seg, i) => seg === cs[i]);
-}
+ * 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()
+ */
+declare function useBlocker(fn: BlockerFn): Blocker;
 /**
-* Detect a stale chunk error — happens post-deploy when the browser requests
-* a hashed filename that no longer exists on the server. Trigger a full reload
-* so the user gets the new bundle instead of a broken loading state.
-*/
-function isStaleChunk(err) {
-  if (err instanceof TypeError && String(err.message).includes("Failed to fetch")) return true;
-  if (err instanceof SyntaxError) return true;
-  return false;
-}
-
+ * 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
+ */
+declare function useSearchParams<T extends Record<string, string>>(defaults?: T): [get: () => T, set: (updates: Partial<T>) => Promise<void>];
+declare function createRouter(options: RouterOptions | RouteRecord[]): Router;
 //#endregion
-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
+export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useLoaderData, useRoute, useRouter, useSearchParams };
+//# sourceMappingURL=index2.d.ts.map