waymark 0.2.3 → 0.3.0

package/README.md

@@ -31,7 +31,7 @@ Waymark is a routing library for React built around three core ideas: **type saf
 
 ---
 
-## Table of contents
+# Table of contents
 
 - [Showcase](#showcase)
 - [Installation](#installation)
@@ -48,35 +48,37 @@ Waymark is a routing library for React built around three core ideas: **type saf
 - [Navigation](#navigation)
   - [The Link component](#the-link-component)
   - [Active state detection](#active-state-detection)
-  - [Link preloading](#link-preloading)
+  - [Route preloading](#route-preloading)
   - [Programmatic navigation](#programmatic-navigation)
   - [Declarative navigation](#declarative-navigation)
 - [Lazy loading](#lazy-loading)
+- [Data preloading](#data-preloading)
 - [Error boundaries](#error-boundaries)
 - [Suspense boundaries](#suspense-boundaries)
 - [Route handles](#route-handles)
 - [Route matching and ranking](#route-matching-and-ranking)
 - [History implementations](#history-implementations)
-- [Server-side rendering (SSR)](#server-side-rendering-ssr)
 - [Cookbook](#cookbook)
+  - [Quick start example](#quick-start-example)
+  - [Server-side rendering (SSR)](#server-side-rendering-ssr)
   - [Scroll to top on navigation](#scroll-to-top-on-navigation)
+  - [Matching a route anywhere](#matching-a-route-anywhere)
   - [Global link configuration](#global-link-configuration)
   - [History middleware](#history-middleware)
   - [View transitions](#view-transitions)
-  - [Matching a route anywhere](#matching-a-route-anywhere)
 - [API reference](#api-reference)
   - [Router class](#router-class)
   - [Route class](#route-class)
-  - [History interface](#history-interface)
   - [Hooks](#hooks)
   - [Components](#components)
+  - [History interface](#history-interface)
   - [Types](#types)
 - [Roadmap](#roadmap)
 - [License](#license)
 
 ---
 
-## Showcase
+# Showcase
 
 Here's what a small routing setup looks like. Define some routes, render them, and get full type safety:
 
@@ -117,7 +119,7 @@ Links, navigation, path params, search params - everything autocompletes and typ
 
 ---
 
-## Installation
+# Installation
 
 ```bash
 npm install waymark
@@ -127,7 +129,7 @@ Waymark requires React 18 or higher.
 
 ---
 
-## Defining routes
+# Defining routes
 
 Routes are created using the `route()` function, following the [builder pattern](https://dev.to/superviz/design-pattern-7-builder-pattern-10j4). You pass it a path and chain methods to configure the route.
 
@@ -161,11 +163,11 @@ Route building is immutable: every method on a route returns a new route instanc
 
 ---
 
-## Nested routes and layouts
+# Nested routes and layouts
 
-Nesting is the core mechanism for building layouts and route hierarchies in Waymark. When you call `.route()` on an existing route, you create a child route that inherits everything from the parent: its path as a prefix, its params, its components, its handles, and its search mappers.
+Nesting is the core mechanism for building layouts and route hierarchies in Waymark. When you call `.route()` on an existing route, you create a child route that inherits everything from the parent: its path as a prefix, its params, its components, etc.
 
-Here's how it works. Let's start with a layout route:
+Here's how it works. Start with any route:
 
 ```tsx
 const dashboard = route("/dashboard").component(DashboardLayout);
@@ -181,7 +183,7 @@ const profile = dashboard.route("/profile").component(Profile);
 
 The child routes combine the parent's path pattern with their own. So `overview` has the full pattern `/dashboard`, `settings` has `/dashboard/settings`, and `profile` has `/dashboard/profile`.
 
-For this to work, the parent component must render an `<Outlet />` where these children should appear:
+The parent component must render an `<Outlet />` where child routes should appear:
 
 ```tsx
 function DashboardLayout() {
@@ -220,7 +222,7 @@ Each level must include an `<Outlet />` to render the next level.
 
 ---
 
-## Setting up the router
+# Setting up the router
 
 Before setting up the router, you need to collect your navigable routes into an array. When building nested route hierarchies, you'll often create intermediate parent routes solely for grouping and shared layouts. These intermediate routes shouldn't be included in your routes array - only the final, navigable routes should be:
 
@@ -236,7 +238,7 @@ const about = layout.route("/about").component(About);
 const routes = [home, about]; // ✅ Don't include `layout`
 ```
 
-This keeps your route list clean and makes sure that only actual pages can be matched and appear in autocomplete. The intermediate routes still exist as part of the hierarchy, they just aren't directly navigable.
+This makes sure that only actual pages can be matched and appear in autocomplete. The intermediate routes still exist as part of the hierarchy, they just aren't directly navigable. Note that the order of routes in the array doesn't matter - Waymark uses a [ranking algorithm](#route-matching-and-ranking) to pick the most specific match.
 
 The `RouterRoot` component is the entry point to Waymark. It listens to URL changes, matches the current path against your routes, and renders the matching route's component hierarchy.
 
@@ -258,7 +260,7 @@ You can also pass a `basePath` if your app lives under a subpath:
 <RouterRoot routes={routes} basePath="/my-app" />
 ```
 
-The second approach is to create a `Router` instance outside of React. This is useful when you need to access the router from anywhere in your code, for example to navigate programmatically from a non-React context:
+The second approach is to create a `Router` instance outside of React. This gives you a global router instance that can be accessed from non-React contexts (e.g., utility functions, service modules, or other non-React code):
 
 ```tsx
 import { Router, RouterRoot } from "waymark";
@@ -288,7 +290,7 @@ With this in place, `Link`, `navigate`, `useParams`, `useSearch`, and other APIs
 
 ---
 
-## Code organization
+# Code organization
 
 There's no prescribed way to organize your routing code. Since Waymark isn't file-based routing, the structure is entirely up to you.
 
@@ -337,11 +339,11 @@ declare module "waymark" {
 }
 ```
 
-But again, this is just one approach. You could keep all routes in a single file, split them by feature, organize them by route depth, whatever fits your project. Waymark doesn't care where the route objects come from or how you structure your files.
+But again, this is just one approach. You could keep all routes in a single file, split them by feature, organize them by route depth, whatever fits your project. Waymark doesn't care where the routes come from or how you structure your files.
 
 ---
 
-## Path params
+# Path params
 
 Dynamic segments in route patterns become typed path params. Define them with a colon prefix. They can also be made optional.
 
@@ -383,11 +385,11 @@ function FileBrowser() {
 
 ---
 
-## Search params
+# Search params
 
-### Basic usage
+## Basic usage
 
-Search params (the `?key=value` part of URLs) can be typed and validated using the `.search()` method on a route. You can pass either a [Standard Schema](https://standardschema.dev/schema#what-schema-libraries-implement-the-spec) validator like Zod, or a plain mapping function.
+Search params (the `?key=value` part of URLs) can be typed and validated using the `.search()` method on a route. You can pass either a [Standard Schema](https://standardschema.dev/schema#what-schema-libraries-implement-the-spec) validator like Zod, or a plain validation function.
 
 With Zod:
 
@@ -415,7 +417,9 @@ const searchPage = route("/search")
   .component(SearchPage);
 ```
 
-Access search params with `useSearch`, which returns a tuple of the current values and a setter function:
+Since you can't control what users put in the URL, your validator should handle missing or malformed values gracefully - validate and normalize rather than reject.
+
+Access validated search params with `useSearch`, which returns a tuple of the current values and a setter function:
 
 ```tsx
 function SearchPage() {
@@ -438,12 +442,12 @@ Pass `true` as the second argument to replace the history entry instead of pushi
 setSearch({ page: 1 }, true);
 ```
 
-### JSON-first approach
+## JSON-first approach
 
 Waymark uses a JSON-first approach for search params, similar to TanStack Router. When serializing and deserializing values from the URL:
 
-- Plain strings that aren't valid JSON are kept as-is: `"John"` → `?name=John` → `"John"`
-- Everything else is JSON-encoded (and URL-encoded):
+- Plain strings that aren't valid JSON are kept as-is (and URL-encoded): `"John"` → `?name=John` → `"John"`
+- Everything else is JSON-encoded (then URL-encoded):
   - `true` → `?enabled=true` → `true`
   - `"true"` → `?enabled=%22true%22` → `"true"`
   - `[1, 2]` → `?filters=%5B1%2C2%5D` → `[1, 2]`
@@ -451,9 +455,9 @@ Waymark uses a JSON-first approach for search params, similar to TanStack Router
 
 This means you can store complex data structures like arrays and objects in search params without manual serialization. When reading from the URL, Waymark automatically parses JSON values back to their original types.
 
-The resulting parsed object is what gets passed to the `.search()` function or schema on the route builder. It's typed as `Record<string, unknown>`, which is why validation with Zod or a mapping function is useful - it lets you transform these unknown values into a typed, validated shape that your components can safely use.
+The resulting parsed object is what gets passed to the `.search()` function or schema on the route builder. It's typed as `Record<string, unknown>`, which is why validation is useful - it lets you transform these unknown values into a typed, validated shape that your components can safely use.
 
-### Inheritance
+## Inheritance
 
 When you define search params with a validator on a route, all child routes automatically inherit that validator along with its typing.
 
@@ -480,7 +484,7 @@ function ProjectsPage() {
 }
 ```
 
-If a child route needs additional search params, define a new validator with `.search()`. Your validator receives the raw params from the URL along with the parent's already-validated params. After validation, your result is combined with the parent's validated params to produce the final search params object.
+If a child route needs additional search params, define a new validator with `.search()`. Your validator receives the raw params from the URL merged with the parent's already-validated params. After validation, your result is combined with the parent's validated params to produce the final search params object.
 
 In practice, this means you only need to validate the new params you're adding - the parent's params are automatically included in the final result:
 
@@ -501,7 +505,7 @@ function ProjectsPage() {
 }
 ```
 
-### Idempotency requirement
+## Idempotency requirement
 
 The validation function or schema you pass to `.search()` must be **idempotent**, meaning `fn(fn(x))` should equal `fn(x)`.
 
@@ -509,9 +513,9 @@ When you read search params, the values are passed through your validator. When
 
 ---
 
-## Navigation
+# Navigation
 
-### The Link component
+## The Link component
 
 The `Link` component renders an anchor tag that navigates without a full page reload. It accepts a `to` prop that can be either a route pattern string or a route object:
 
@@ -560,7 +564,7 @@ The `asChild` prop lets you use your own component while keeping Link's behavior
 </Link>
 ```
 
-### Active state detection
+## Active state detection
 
 Links automatically track whether they match the current URL. When active, they receive a `data-active="true"` attribute and can apply different styles.
 
@@ -594,11 +598,13 @@ Or use the `activeClassName` and `activeStyle` props directly:
 </Link>
 ```
 
-### Link preloading
+## Route preloading
 
-When a route has preloaders, e.g. when using lazy-loaded routes, you can preload them before the user actually navigates. This makes the subsequent navigation instant. The `preload` prop controls when preloading happens:
+Links can optionally trigger route preloading before navigation occurs. When preloading is enabled, any [lazy-loaded components](#lazy-loading) (defined with `.lazy()`) and [preload functions](#data-preloading) (defined with `.preload()`) are called early. This improves perceived performance by loading component bundles and running preparation logic like prefetching data ahead of time.
 
-**`preload="intent"`** triggers preloading when the user shows intent to navigate by hovering over the link or focusing it. This is the most common choice as it balances eager loading with not wasting bandwidth:
+The `preload` prop controls when preloading happens:
+
+**`preload="intent"`** preloads when the user shows intent to navigate by hovering or focusing the link. This is the most common choice as it balances eager loading with not wasting bandwidth:
 
 ```tsx
 <Link to="/heavy-page" preload="intent">
@@ -624,15 +630,26 @@ When a route has preloaders, e.g. when using lazy-loaded routes, you can preload
 
 **`preload={false}`** disables preloading entirely. This is the default.
 
-You can also preload routes programmatically by calling the route's `.preload()` method:
+To prevent unwanted preloads from quick hover/focus interactions, Link waits 50ms before triggering. You can customize this with `preloadDelay`:
 
 ```tsx
-userProfile.preload();
+<Link to="/heavy-page" preload="intent" preloadDelay={100}>
+  Heavy page
+</Link>
 ```
 
-### Programmatic navigation
+You can also preload programmatically using `router.preload()`:
 
-For navigation triggered by code rather than user clicks, use the `useNavigate` hook (or `router.navigate`):
+```tsx
+const router = useRouter();
+router.preload({ to: userProfile, params: { id: "42" } });
+```
+
+To set a preload strategy globally for all links in your app, see [Global link configuration](#global-link-configuration).
+
+## Programmatic navigation
+
+For navigation triggered by code rather than user clicks, use the `useNavigate` hook:
 
 ```tsx
 import { useNavigate } from "waymark";
@@ -665,20 +682,24 @@ navigate(1); // Go forward
 navigate(-2); // Go back two steps
 ```
 
-You can also access the router directly via `useRouter()` (or import the router if created outside of React) and call its `navigate` method, which works the same way.
+You can also access the router directly via `useRouter()` (or import the router if created outside of React) and call its `navigate` method, which works the same way:
 
-For unsafe navigation that bypasses type checking, you can pass `url` instead of `to`, `params` and `search`. This is useful when you don't know the target URL statically (e.g. external redirects):
+```tsx
+router.navigate({ to: "/login" });
+```
+
+For unsafe navigation that bypasses type checking, you can pass `url` instead of `to`, `params` and `search`. This is useful when you don't know the target URL statically (e.g., URLs from user input or API responses):
 
 ```tsx
 // Type-safe navigation
 navigate({ to: userProfile, params: { id: "42" } });
 
 // Unsafe navigation - no type checking
-navigate({ url: "/some/unknown/path" });
+navigate({ url: "/some/path?tab=settings" });
 navigate({ url: "/callback", replace: true, state: { data: 123 } });
 ```
 
-### Declarative navigation
+## Declarative navigation
 
 For redirects triggered by rendering rather than events, use the `Navigate` component. It navigates as soon as it mounts, making it useful for conditional redirects based on application state:
 
@@ -696,7 +717,7 @@ function ProtectedPage() {
 }
 ```
 
-The `Navigate` component accepts the same navigation props as the `Link` component. You can pass route patterns, path params, search params, and state:
+The `Navigate` component accepts the same navigation props as the `Link` component:
 
 ```tsx
 <Navigate to="/users/:id" params={{ id: "42" }} search={{ tab: "posts" }} />
@@ -708,7 +729,7 @@ Note that `Navigate` uses `useLayoutEffect` internally to ensure the navigation
 
 ---
 
-## Lazy loading
+# Lazy loading
 
 Load route components on demand with `.lazy()`. The function you pass should return a dynamic import:
 
@@ -743,11 +764,52 @@ const settings = dashboard.route("/settings").component(Settings);
 
 When navigating to `/dashboard/settings`, React loads the dashboard component first, then renders settings inside it. The Dashboard component must include an `<Outlet />` for the child route to appear.
 
-See [Link preloading](#link-preloading) for ways to load these components before the user navigates.
+See [Route preloading](#route-preloading) for ways to load these components before the user navigates.
+
+---
+
+# Data preloading
+
+Use `.preload()` to run logic before navigation occurs, typically to prefetch data. Preload functions receive the target route's typed params and search values:
+
+```tsx
+const userProfile = route("/users/:id")
+  .search(z.object({ tab: z.enum(["posts", "comments"]).catch("posts") }))
+  .preload(async ({ params, search }) => {
+    await queryClient.prefetchQuery({
+      queryKey: ["user", params.id, search.tab],
+      queryFn: () => fetchUser(params.id, search.tab)
+    });
+  })
+  .component(UserProfile);
+```
+
+See [Route preloading](#route-preloading) for how to trigger preload functions.
+
+Depending on when and how preloading is triggered, these functions may run repeatedly. Waymark intentionally doesn't cache or deduplicate the calls - that's the job of your data layer. Libraries like TanStack Query, SWR, or Apollo handle this well. For example, TanStack Query's `staleTime` prevents refetches when data is still fresh:
+
+```tsx
+await queryClient.prefetchQuery({
+  queryKey: ["user", params.id],
+  queryFn: () => fetchUser(params.id),
+  staleTime: 60_000 // No refetch within 60s
+});
+```
+
+Preload functions inherit to child routes:
+
+```tsx
+const dashboard = route("/dashboard")
+  .preload(prefetchDashboardData)
+  .component(DashboardLayout);
+
+const settings = dashboard.route("/settings").component(Settings);
+// Preloading /dashboard/settings runs prefetchDashboardData
+```
 
 ---
 
-## Error boundaries
+# Error boundaries
 
 Catch errors thrown during rendering with `.error()`. The error component receives the error as a prop:
 
@@ -771,11 +833,11 @@ Error boundaries catch errors from all nested content. A common pattern is to pl
 const app = route("/").error(ErrorPage).component(AppLayout);
 ```
 
-The error boundary automatically resets when navigation occurs, giving the new route a fresh start.
+To give new routes a fresh start, the error boundary automatically resets when navigation occurs.
 
 ---
 
-## Suspense boundaries
+# Suspense boundaries
 
 When using lazy loading or React's `use()` hook for data fetching, you may want to add suspense boundaries to show loading states. Add them with `.suspense()`:
 
@@ -804,7 +866,7 @@ Note: React 19 has a [known throttling behavior](https://github.com/facebook/rea
 
 ---
 
-## Route handles
+# Route handles
 
 Handles let you attach static arbitrary metadata to routes. This is useful for breadcrumbs, page titles, access control flags, or any other static data you want to associate with a route.
 
@@ -830,8 +892,8 @@ function Breadcrumbs() {
     <nav>
       {handles.map((h, i) => (
         <span key={i}>
+          {i !== 0 && " / "}
           {h.title}
-          {i < handles.length - 1 && " / "}
         </span>
       ))}
     </nav>
@@ -854,7 +916,7 @@ declare module "waymark" {
 
 ---
 
-## Route matching and ranking
+# Route matching and ranking
 
 When a user navigates to a URL, Waymark needs to determine which route matches. Since multiple routes can potentially match the same path (think `/users/:id` vs `/users/new`), Waymark uses a ranking algorithm to pick the most specific one.
 
@@ -906,7 +968,7 @@ const routes = [
 
 ---
 
-## History implementations
+# History implementations
 
 History is an abstraction layer that sits between the router and the actual low-level navigation logic. It handles reading and updating the current location, managing navigation state, and notifying when the URL changes. This abstraction allows Waymark to work in different environments (browser, hash-based, in-memory, server-side, tests, etc.) without changing the router's core logic. You can switch between environments simply by swapping the history implementation - the rest of your app stays exactly the same.
 
@@ -940,11 +1002,53 @@ All history implementations conform to the `HistoryLike` interface, so you can c
 
 ---
 
-## Server-side rendering (SSR)
+# Cookbook
 
-Waymark supports server-side rendering using `MemoryHistory`. The key is to use `MemoryHistory` on the server (initialized with the request URL) and `BrowserHistory` on the client.
+## Quick start example
 
-On the server, create a router with `MemoryHistory` initialized to the request URL:
+Here's a minimal but complete routing setup with a layout and two pages:
+
+```tsx
+import { route, RouterRoot, Outlet, Link } from "waymark";
+
+// Layout route
+const app = route("/").component(AppLayout);
+
+function AppLayout() {
+  return (
+    <div>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+      </nav>
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+
+// Page routes
+const home = app.route("/").component(() => <h1>Welcome home</h1>);
+const about = app.route("/about").component(() => <h1>About us</h1>);
+
+// Router setup
+const routes = [home, about];
+
+export function App() {
+  return <RouterRoot routes={routes} />;
+}
+
+declare module "waymark" {
+  interface Register {
+    routes: typeof routes;
+  }
+}
+```
+
+## Server-side rendering (SSR)
+
+Waymark supports server-side rendering using `MemoryHistory`. The key is to use `MemoryHistory` on the server (initialized with the request URL) and `BrowserHistory` on the client:
 
 ```tsx
 // server.tsx
@@ -980,16 +1084,12 @@ import { hydrateRoot } from "react-dom/client";
 import { RouterRoot } from "waymark";
 import { routes } from "./routes";
 
-hydrateRoot(document.getElementById("root")!, <RouterRoot routes={routes} />);
+hydrateRoot(rootElement, <RouterRoot routes={routes} />);
 ```
 
 You can also manually set `ssrContext.statusCode` in your components during SSR to control the response status (like 404 for not found pages).
 
----
-
-## Cookbook
-
-### Scroll to top on navigation
+## Scroll to top on navigation
 
 Create a component that scrolls to top when the path changes and include it in your layout:
 
@@ -1014,7 +1114,48 @@ function AppLayout() {
 }
 ```
 
-### Global link configuration
+## Matching a route anywhere
+
+Use `useMatch` to check if a route matches the current path from anywhere in your component tree. You can pass either a route pattern string or a route object, just like with `Link` and `navigate`. This is useful for conditional rendering, styling, access control, and more. It's also used internally by `useParams` and `Link`.
+
+By default, `useMatch` uses loose matching where the current path only needs to start with the route's path. To require an exact match instead, pass `strict: true`:
+
+```tsx
+import { useMatch } from "waymark";
+
+const dashboard = route("/dashboard").component(Dashboard);
+const settings = route("/settings").component(Settings);
+
+function Sidebar() {
+  // Loose matching: matches /dashboard and /dashboard/literally/anything
+  const dashboardMatch = useMatch({ from: "/dashboard" });
+
+  // Strict matching: matches only /settings
+  const settingsMatch = useMatch({ from: settings, strict: true });
+
+  return (
+    <nav>
+      {dashboardMatch && <DashboardMenu />}
+      {settingsMatch && <SettingsSubmenu />}
+    </nav>
+  );
+}
+```
+
+You can also filter by param values to match only specific instances:
+
+```tsx
+const adminMatch = useMatch({
+  from: "/users/:id",
+  params: { id: "admin" }
+});
+
+if (adminMatch) {
+  // Currently viewing the admin user
+}
+```
+
+## Global link configuration
 
 Set defaults for all `Link` components using `defaultLinkOptions` on the router. Useful for consistent styling and preload behavior across your app:
 
@@ -1023,6 +1164,7 @@ Set defaults for all `Link` components using `defaultLinkOptions` on the router.
   routes={routes}
   defaultLinkOptions={{
     preload: "intent",
+    preloadDelay: 75,
     className: "app-link",
     activeClassName: "active"
   }}
@@ -1031,7 +1173,7 @@ Set defaults for all `Link` components using `defaultLinkOptions` on the router.
 
 Individual links can override any of these defaults by passing their own props.
 
-### History middleware
+## History middleware
 
 This is a design pattern rather than a feature. You can extend history behavior for logging, analytics, or other side effects by monkey-patching the history instance:
 
@@ -1070,7 +1212,7 @@ const router = new Router({
 });
 ```
 
-### View transitions
+## View transitions
 
 You can use the view transitions API for smoother page animations. Create a history middleware that wraps navigation in a view transition:
 
@@ -1110,67 +1252,14 @@ Add CSS to control the transition:
 
 For more advanced techniques, see the [MDN documentation on View Transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API).
 
-### Matching a route anywhere
-
-Use `useMatch` to check if a route matches the current path from anywhere in your component tree. You can pass either a route pattern string or a route object, just like with `Link` and `navigate`. This is useful for conditional rendering, styling, access control, and more. It's also used internally by `useParams` and `Link`.
-
-```tsx
-import { useMatch } from "waymark";
-
-const dashboard = route("/dashboard").component(Dashboard);
-const settings = route("/settings").component(Settings);
-
-function Sidebar() {
-  // Using route patterns
-  const dashboardMatch = useMatch({ from: "/dashboard" });
-  const settingsMatch = useMatch({ from: "/settings", strict: true });
-
-  // Using route objects
-  const dashboardMatch = useMatch({ from: dashboard });
-  const settingsMatch = useMatch({ from: settings, strict: true });
-
-  return (
-    <nav>
-      {dashboardMatch && <DashboardMenu />}
-      {settingsMatch && <SettingsSubmenu />}
-    </nav>
-  );
-}
-```
-
-You can also filter by param values to match only specific instances:
-
-```tsx
-const adminMatch = useMatch({
-  from: "/users/:id",
-  params: { id: "admin" }
-});
-
-if (adminMatch) {
-  // Currently viewing the admin user
-}
-```
-
 ---
 
-## API reference
+# API reference
 
-### Router class
+## Router class
 
 The `Router` class is the core of Waymark. You can create an instance directly or let `RouterRoot` create one.
 
-**Constructor:**
-
-```tsx
-const router = new Router({
-  basePath: string, // Optional: base path prefix (default: "/")
-  routes: Route[], // Required: array of routes
-  history: HistoryLike, // Optional: history implementation (default: BrowserHistory)
-  ssrContext: SSRContext, // Optional: SSR context
-  defaultLinkOptions: LinkOptions // Optional: defaults for all Links
-});
-```
-
 **Properties:**
 
 - `router.basePath` - The configured base path
@@ -1179,9 +1268,21 @@ const router = new Router({
 - `router.ssrContext` - The SSR context (if provided)
 - `router.defaultLinkOptions` - Default link options
 
-**Methods:**
+**`new Router(options)`** creates a new router.
+
+- `options` - `RouterOptions` - Router configuration
+- Returns: `Router` - A new router instance
+
+```tsx
+const router = new Router({ routes });
+const router = new Router({ routes, basePath: "/app" });
+const router = new Router({ routes, history: new HashHistory() });
+```
+
+**`router.navigate(options)`** navigates to a new location.
 
-`router.navigate(options)` navigates to a new location:
+- `options` - `NavigateOptions | HistoryPushOptions | number` - Type-safe navigation options, untyped navigation options, or a history delta
+- Returns: `void`
 
 ```tsx
 // Type-safe navigation
@@ -1195,38 +1296,64 @@ router.navigate(-1); // Back
 router.navigate(1); // Forward
 ```
 
-`router.createUrl(options)` builds a URL string without navigating:
+**`router.createUrl(options)`** builds a URL string.
+
+- `options` - `NavigateOptions` - Type-safe navigation options
+- Returns: `string` - The constructed URL
 
 ```tsx
 const url = router.createUrl({ to: userProfile, params: { id: "42" } });
 // Returns "/users/42"
 ```
 
-`router.match(path, options)` checks if a path matches a specific route:
+**`router.match(path, options)`** checks if a path matches a specific route.
+
+- `path` - `string` - The path to match against
+- `options` - `MatchOptions` - Matching options
+- Returns: `Match | null` - The match result or null if no match
 
 ```tsx
 const match = router.match("/users/42", { from: "/users/:id" });
 // Returns { route, params: { id: "42" } } or null
 ```
 
-`router.matchAll(path)` finds the best matching route from all registered routes:
+**`router.matchAll(path)`** finds the best match from all registered routes.
+
+- `path` - `string` - The path to match against
+- Returns: `Match | null` - The best match or null if no route matches
 
 ```tsx
 const match = router.matchAll("/users/42");
 // Returns the best match or null
 ```
 
-`router.getRoute(pattern)` retrieves a route by its pattern:
+**`router.getRoute(pattern)`** get a route by its pattern.
+
+- `pattern` - `Pattern | Route` - A route pattern string or a route object
+- Returns: `Route` - The route object; throws if not found
 
 ```tsx
 const route = router.getRoute("/users/:id");
 ```
 
-### Route class
+**`router.preload(options)`** triggers preloading for a route.
+
+- `options` - `NavigateOptions` - Type-safe navigation options
+- Returns: `Promise<void>` - Resolves when preloaded
+
+```tsx
+await router.preload({ to: "/user/:id", params: { id: "42" } });
+await router.preload({ to: searchPage, search: { q: "test" } });
+```
+
+## Route class
 
 Routes are created with the `route()` function and configured by chaining methods.
 
-**`route(pattern)`** creates a new route:
+**`route(pattern)`** creates a new route.
+
+- `pattern` - `string` - The route path pattern (e.g., `"/users"`, `"/users/:id"`, `"/*"`)
+- Returns: `Route` - A new route object
 
 ```tsx
 const users = route("/users");
@@ -1234,38 +1361,62 @@ const user = route("/users/:id");
 const catchAll = route("/*");
 ```
 
-**`.route(subPattern)`** creates a nested child route:
+**`.route(pattern)`** creates a nested child route.
+
+- `pattern` - `string` - The child path pattern to append
+- Returns: `Route` - A new route object
 
 ```tsx
 const userSettings = user.route("/settings");
 // Pattern becomes "/users/:id/settings"
 ```
 
-**`.component(component)`** adds a React component to render:
+**`.component(component)`** adds a component to render when this route matches.
+
+- `component` - `ComponentType` - A React component
+- Returns: `Route` - A new route object
 
 ```tsx
 const users = route("/users").component(UsersPage);
 ```
 
-**`.lazy(loader)`** adds a lazy-loaded component to render:
+**`.lazy(loader)`** adds a lazy-loaded component to render when this route matches.
+
+- `loader` - `ComponentLoader` - A function returning a dynamic import promise
+- Returns: `Route` - A new route object
 
 ```tsx
 const users = route("/users").lazy(() => import("./UsersPage"));
+const admin = route("/admin").lazy(() =>
+  import("./Admin").then(m => m.AdminPage)
+);
 ```
 
-**`.search(validator)`** adds search parameter validation:
+**`.search(validate)`** adds search parameter validation.
+
+- `validate` - `StandardSchema | ((search) => ValidatedSearch)` - A Standard Schema (like Zod) or a validation function
+- Returns: `Route` - A new route object
 
 ```tsx
 const search = route("/search").search(z.object({ q: z.string() }));
+const filter = route("/filter").search(raw => ({
+  term: String(raw.term ?? "")
+}));
 ```
 
-**`.handle(data)`** attaches static metadata:
+**`.handle(handle)`** attaches static metadata to the route.
+
+- `handle` - `Handle` - Arbitrary metadata
+- Returns: `Route` - A new route object
 
 ```tsx
 const admin = route("/admin").handle({ requiresAuth: true });
 ```
 
-**`.suspense(fallback)`** wraps children in a suspense boundary:
+**`.suspense(fallback)`** wraps nested content in a Suspense boundary.
+
+- `fallback` - `ComponentType` - The fallback component to show while suspended
+- Returns: `Route` - A new route object
 
 ```tsx
 const lazy = route("/lazy")
@@ -1273,258 +1424,319 @@ const lazy = route("/lazy")
   .lazy(() => import("./Page"));
 ```
 
-**`.error(fallback)`** wraps children in an error boundary:
+**`.error(fallback)`** wraps nested content in an error boundary.
+
+- `fallback` - `ComponentType<{ error: unknown }>` - The fallback component, receives the caught error as a prop
+- Returns: `Route` - A new route object
 
 ```tsx
 const risky = route("/risky").error(ErrorPage).component(RiskyPage);
 ```
 
-**`.preloader(loader)`** registers a preloader function that will be called when `.preload()` is invoked or when a `Link` with a preload strategy triggers it:
+**`.preload(preload)`** registers a preload function for the route.
+
+- `preload` - `(context: PreloadContext) => Promise<any>` - An async function receiving typed `params` and `search`
+- Returns: `Route` - A new route object
 
 ```tsx
-const users = route("/users").preloader(async () => {
-  await prefetchData();
-});
+const user = route("/users/:id")
+  .search(z.object({ tab: z.string().catch("profile") }))
+  .preload(async ({ params, search }) => {
+    // params.id: string, search.tab: string - fully typed
+    await prefetchUser(params.id, search.tab);
+  });
 ```
 
-**`.preload()`** manually triggers all registered preloaders (including lazy component loading):
+## Hooks
+
+**`useRouter()`** returns the Router instance from context.
+
+- Returns: `Router` - The router instance
 
 ```tsx
-await userProfile.preload();
+const router = useRouter();
 ```
 
-### History interface
-
-The `History` interface defines how Waymark interacts with navigation. All history implementations conform to this interface.
+**`useNavigate()`** returns a navigation function.
 
-**Interface:**
+- Returns: `(options: NavigateOptions | HistoryPushOptions | number) => void` - The navigate function
 
 ```tsx
-interface HistoryLike {
-  getPath: () => string;
-  getSearch: () => Record<string, unknown>;
-  getState: () => any;
-  go: (delta: number) => void;
-  push: (options: HistoryPushOptions) => void;
-  subscribe: (listener: () => void) => () => void;
-}
+const navigate = useNavigate();
+navigate({ to: "/home" });
+navigate(-1);
 ```
 
-**Methods:**
+**`useLocation()`** returns the current location, subscribes to changes.
 
-`history.getPath()` returns the current pathname:
+- Returns: `{ path: string, search: Record<string, unknown>, state: any }` - The current path, parsed search params, and history state
 
 ```tsx
-const path = history.getPath();
-// Returns "/users/42"
+const { path, search, state } = useLocation();
 ```
 
-`history.getSearch()` returns the current search params as a parsed object:
+**`useOutlet()`** returns the child route content.
+
+- Returns: `ReactNode` - The child route's content or null
 
 ```tsx
-const search = history.getSearch();
-// Returns { tab: "posts", page: 2 }
+const outlet = useOutlet();
 ```
 
-`history.getState()` returns the current history state:
+**`useParams(route)`** returns typed path params for a route.
+
+- `route` - `Pattern | Route` - A route pattern string or route object
+- Returns: `Params` - The extracted path params, fully typed
 
 ```tsx
-const state = history.getState();
-// Returns any state passed during navigation
+const { id } = useParams(userRoute);
 ```
 
-`history.go(delta)` navigates forward or back in history:
+**`useSearch(route)`** returns validated search params and a setter function.
+
+- `route` - `Pattern | Route` - A route pattern string or route object
+- Returns: `[Search, SetSearch]` - A tuple of the validated search params and a setter; the setter accepts a partial update or an updater function, with an optional second argument to replace instead of push
 
 ```tsx
-history.go(-1); // Go back
-history.go(1); // Go forward
-history.go(-2); // Go back two steps
+const [search, setSearch] = useSearch(searchRoute);
+setSearch({ page: 2 });
+setSearch(prev => ({ page: prev.page + 1 }));
+setSearch({ page: 1 }, true); // Replace instead of push
 ```
 
-`history.push(options)` pushes or replaces a history entry:
+**`useMatch(options)`** checks if a route matches the current path.
+
+- `options` - `MatchOptions` - Matching options
+- Returns: `Match | null` - The match result or null if no match
 
 ```tsx
-history.push({ url: "/users/42", state: { from: "list" } });
-history.push({ url: "/login", replace: true });
+const match = useMatch({ from: "/users/:id" });
+const strictMatch = useMatch({ from: "/users", strict: true });
+const filteredMatch = useMatch({ from: "/users/:id", params: { id: "admin" } });
 ```
 
-`history.subscribe(listener)` subscribes to navigation events and returns an unsubscribe function:
+**`useHandles()`** returns the handles from the matched route chain.
 
-```tsx
-const unsubscribe = history.subscribe(() => {
-  console.log("Navigation occurred");
-});
+- Returns: `Handle[]` - Array of handles
 
-// Later: unsubscribe()
+```tsx
+const handles = useHandles();
 ```
 
-### Hooks
+## Components
+
+**`RouterRoot`** sets up routing context and renders your routes.
 
-**`useRouter()`** returns the Router instance:
+- `props` - `RouterOptions | { router: Router }` - Either router options (same as the `Router` constructor) or a router instance
 
 ```tsx
-const router = useRouter();
+<RouterRoot routes={routes} basePath="/app" history={history} />
+<RouterRoot router={router} />
 ```
 
-**`useNavigate()`** returns a navigation function:
+**`Outlet`** renders the child route content.
 
 ```tsx
-const navigate = useNavigate();
-navigate({ to: "/home" });
-navigate(-1);
+function Layout() {
+  return (
+    <div>
+      <Outlet />
+    </div>
+  );
+}
 ```
 
-**`useLocation()`** returns the current location:
+**`Link`** renders an anchor tag for navigation.
+
+- `props` - `NavigateOptions & LinkOptions & { asChild?: boolean }` - Navigation options, link options, and optional `asChild` to use a child element as the anchor; other props are passed through
 
 ```tsx
-const { path, search, state } = useLocation();
-// path: string, search: Record<string, unknown>, state: any
+<Link to="/path" params={...} search={...} replace strict preload="intent">
+  Click me
+</Link>
 ```
 
-**`useOutlet()`** returns the nested route content (used internally by `Outlet`):
+**`Navigate`** redirects on render.
+
+- `props` - `NavigateOptions` - The navigation target
 
 ```tsx
-const outlet = useOutlet();
+<Navigate to="/login" replace />
 ```
 
-**`useParams(route)`** returns typed parameters for a route:
+## History interface
+
+The `HistoryLike` interface defines how Waymark interacts with navigation. All history implementations conform to this interface.
+
+**Available implementations:**
 
 ```tsx
-const { id } = useParams(userRoute);
+new BrowserHistory(); // Browser History API (/posts/123). Default.
+new HashHistory(); // URL hash (/#/posts/123).
+new MemoryHistory("/initial"); // In-memory only.
 ```
 
-**`useSearch(route)`** returns search params and a setter:
+See [History implementations](#history-implementations) for detailed usage.
+
+**`history.getPath()`** returns the current path.
+
+- Returns: `string` - The current path
 
 ```tsx
-const [search, setSearch] = useSearch(searchRoute);
-setSearch({ page: 2 });
-setSearch(prev => ({ page: prev.page + 1 }));
+const path = history.getPath();
+// Returns "/users/42"
 ```
 
-**`useMatch(options)`** checks if a route matches the current path:
+**`history.getSearch()`** returns the current search params as a parsed JSON object.
+
+- Returns: `Record<string, unknown>` - The parsed search params
 
 ```tsx
-const match = useMatch({ from: "/users/:id" });
-const strictMatch = useMatch({ from: "/users", strict: true });
-const filteredMatch = useMatch({ from: "/users/:id", params: { id: "admin" } });
+const search = history.getSearch();
+// Returns { tab: "posts", page: 2 }
 ```
 
-**`useHandles()`** returns all handles from the matched route chain in order:
+**`history.getState()`** returns the current history state.
+
+- Returns: `any` - The state passed during navigation, or undefined
 
 ```tsx
-const handles = useHandles();
+const state = history.getState();
+// Returns any state passed during navigation
 ```
 
-### Components
+**`history.go(delta)`** navigates forward or back in history.
 
-**`RouterRoot`** is the root provider. Pass either router options or a router instance:
+- `delta` - `number` - The number of entries to move
+- Returns: `void`
 
 ```tsx
-<RouterRoot routes={routes} basePath="/app" history={history} />
-<RouterRoot router={router} />
+history.go(-1); // Go back
+history.go(1); // Go forward
+history.go(-2); // Go back two steps
 ```
 
-**`Outlet`** renders child route content:
+**`history.push(options)`** pushes or replaces a history entry.
+
+- `options` - `HistoryPushOptions` - The URL to navigate to, with optional `replace` and `state`
+- Returns: `void`
 
 ```tsx
-function Layout() {
-  return (
-    <div>
-      <Outlet />
-    </div>
-  );
-}
+history.push({ url: "/users/42", state: { from: "list" } });
+history.push({ url: "/login", replace: true });
 ```
 
-**`Link`** navigates on click. Props extend `NavigateOptions` and `LinkOptions`:
+**`history.subscribe(listener)`** subscribes to navigation events.
+
+- `listener` - `() => void` - Callback invoked when any navigation occurs
+- Returns: `() => void` - An unsubscribe function
 
 ```tsx
-<Link to="/path" params={...} search={...} replace strict preload="intent">
-  Click me
-</Link>
+const unsubscribe = history.subscribe(() => {
+  console.log("Navigation occurred");
+});
+
+// Later: unsubscribe()
 ```
 
-**`Navigate`** redirects on render. Props are `NavigateOptions`:
+## Types
+
+**`RouterOptions`** are options for creating a `Router` instance or passing to `RouterRoot`.
 
 ```tsx
-<Navigate to="/login" replace />
+interface RouterOptions {
+  routes: Route[]; // Array of navigable routes (required)
+  basePath?: string; // Base path prefix (default: "/")
+  history?: HistoryLike; // History implementation (default: BrowserHistory)
+  ssrContext?: SSRContext; // Context for server-side rendering
+  defaultLinkOptions?: LinkOptions; // Default options for all Link components
+}
 ```
 
-### Types
-
-**`NavigateOptions<P>`** is the main type for type-safe navigation:
+**`NavigateOptions`** are options for type-safe navigation.
 
 ```tsx
-type NavigateOptions<P extends Pattern> = {
-  to: P | Route<P>; // Route pattern or route object
-  params?: Params<P>; // Required if route has dynamic segments
-  search?: Search<P>; // Search params if route defines them
-  replace?: boolean; // Replace history instead of push
+type NavigateOptions = {
+  to: Pattern | Route; // Route pattern string or route object
+  params?: Params; // Path params
+  search?: Search; // Search params
+  replace?: boolean; // Replace history entry instead of pushing
   state?: any; // Arbitrary state to pass
 };
 ```
 
-**`HistoryPushOptions`** is for untyped navigation:
+**`HistoryPushOptions`** are options for untyped navigation.
 
 ```tsx
 interface HistoryPushOptions {
   url: string; // The URL to navigate to
-  replace?: boolean; // Replace history instead of push
+  replace?: boolean; // Replace history entry instead of pushing
   state?: any; // Arbitrary state to pass
 }
 ```
 
-**`MatchOptions<P>`** is used for route matching:
+**`MatchOptions`** are options for route matching.
 
 ```tsx
-type MatchOptions<P extends Pattern> = {
-  from: P | Route<P>; // Route to match against
-  strict?: boolean; // Require exact match (not just prefix)
-  params?: Partial<Params<P>>; // Match by specific param values
+type MatchOptions = {
+  from: Pattern | Route; // The route to match against
+  strict?: boolean; // Require exact match (default: false, matches prefixes)
+  params?: Partial<Params>; // Optional param values to filter by
 };
 ```
 
-**`Match<P>`** is the result of a successful match:
+**`Match`** is the result of a successful route match.
 
 ```tsx
-type Match<P extends Pattern> = {
-  route: Route<P>; // The matched route
-  params: Params<P>; // Extracted parameters
+type Match = {
+  route: Route; // Matched route object
+  params: Params; // Extracted path params
 };
 ```
 
-**`LinkOptions`** controls link behavior and styling:
+**`LinkOptions`** controls link behavior and styling.
 
 ```tsx
 interface LinkOptions {
-  strict?: boolean; // Strict active matching
-  preload?: "intent" | "render" | "viewport" | false;
-  style?: CSSProperties;
-  className?: string;
-  activeStyle?: CSSProperties;
-  activeClassName?: string;
+  strict?: boolean; // Strict matching for active state detection
+  preload?: "intent" | "render" | "viewport" | false; // When to trigger preloading
+  preloadDelay?: number; // Delay in ms before preloading starts (default: 50)
+  style?: CSSProperties; // Base styles for the link
+  className?: string; // Base class name for the link
+  activeStyle?: CSSProperties; // Additional styles when active
+  activeClassName?: string; // Additional class name when active
 }
 ```
 
-**`SSRContext`** captures context during SSR (like redirects):
+**`SSRContext`** captures context during server-side rendering.
 
 ```tsx
 type SSRContext = {
   redirect?: string; // Set by Navigate component during SSR
-  statusCode?: number; // Can be set manually in your components during SSR
+  statusCode?: number; // Can be set manually for HTTP status
 };
 ```
 
----
+**`PreloadContext`** is the context passed to preload functions.
 
-## Roadmap
+```tsx
+interface PreloadContext {
+  params: Params; // Path params for the route
+  search: Search; // Validated search params
+}
+```
+
+---
 
-Future improvements planned for Waymark:
+# Roadmap
 
-- **Preloader context** - Pass path params and search params to preloader functions, enabling loading logic based on the target route's dynamic data
+- Possibility to pass an arbitrary context to the Router instance for later use in preloads?
+- Relative path navigation? Not sure it's indispensable given that users can export/import route objects and pass them as navigation option.
+- Document usage in test environments
+- Open to suggestions, we can discuss them [here](https://github.com/strblr/waymark/discussions).
 
 ---
 
-## License
+# License
 
 MIT