waymark 0.2.2 → 0.3.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/strblr/waymark/master/banner.svg" alt="Waymark" width="400" />
+  <img src="https://raw.githubusercontent.com/strblr/waymark/master/banner.svg" alt="Waymark" />
 </p>
 
 <p align="center">
@@ -8,28 +8,30 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/waymark"><img src="https://img.shields.io/npm/v/waymark?style=flat-square&color=000&labelColor=000" alt="npm version" /></a>
-  <a href="https://bundlephobia.com/package/waymark"><img src="https://img.shields.io/bundlephobia/minzip/waymark?style=flat-square&color=000&labelColor=000" alt="bundle size" /></a>
+  <a href="https://www.npmjs.com/package/waymark"><img src="https://img.badgesize.io/https://unpkg.com/waymark/dist/index.js?compression=gzip&label=gzip&style=flat-square&color=000&labelColor=000" alt="gzip size" /></a>
   <a href="https://www.npmjs.com/package/waymark"><img src="https://img.shields.io/npm/dm/waymark?style=flat-square&color=000&labelColor=000" alt="downloads" /></a>
   <a href="https://github.com/strblr/waymark/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/waymark?style=flat-square&color=000&labelColor=000" alt="license" /></a>
+  <a href="https://github.com/sponsors/strblr"><img src="https://img.shields.io/github/sponsors/strblr?style=flat-square&color=000&labelColor=000" alt="sponsors" /></a>
 </p>
 
 <p align="center">
-  <a href="https://strblr.github.io/waymark">📖 Documentation</a>
+  <a href="https://waymark.strblr.workers.dev">📖 Documentation</a>
 </p>
 
 ---
 
 Waymark is a routing library for React built around three core ideas: **type safety**, **simplicity**, and **minimal overhead**.
 
-- **Fully type-safe** - Complete TypeScript inference for routes, params, and search queries
+- **Fully type-safe** - Complete TypeScript inference for routes, path params, and search params
 - **Zero config** - No build plugins, no CLI tools, no configuration files, very low boilerplate
 - **Familiar API** - If you've used React Router or TanStack Router, you'll feel at home
-- **3.5kB gzipped** - Extremely lightweight with just one 0.4kB dependency, so less than 4kB total
+- **3.6kB gzipped** - Extremely lightweight with just one 0.4kB dependency, so around 4kB total
+- **Not vibe-coded** - Built with careful design and attention to detail by a human
 - **Just works** - Define routes, get autocomplete everywhere
 
 ---
 
-## Table of contents
+# Table of contents
 
 - [Showcase](#showcase)
 - [Installation](#installation)
@@ -37,39 +39,46 @@ Waymark is a routing library for React built around three core ideas: **type saf
 - [Nested routes and layouts](#nested-routes-and-layouts)
 - [Setting up the router](#setting-up-the-router)
 - [Code organization](#code-organization)
+- [Path params](#path-params)
+- [Search params](#search-params)
+  - [Basic usage](#basic-usage)
+  - [JSON-first approach](#json-first-approach)
+  - [Inheritance](#inheritance)
+  - [Idempotency requirement](#idempotency-requirement)
 - [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)
-- [Path parameters](#path-parameters)
-- [Search queries](#search-queries)
 - [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)
 - [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)
-  - [Types](#types)
   - [Router class](#router-class)
-  - [History interface](#history-interface)
   - [Route class](#route-class)
   - [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:
 
@@ -106,11 +115,11 @@ declare module "waymark" {
 }
 ```
 
-Links, navigation, params, search queries - everything autocompletes and type-checks automatically. That's it. No config files, no build plugins, no CLI.
+Links, navigation, path params, search params - everything autocompletes and type-checks automatically. That's it. No config files, no build plugins, no CLI.
 
 ---
 
-## Installation
+# Installation
 
 ```bash
 npm install waymark
@@ -120,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.
 
@@ -154,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);
@@ -174,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() {
@@ -189,7 +198,7 @@ function DashboardLayout() {
 }
 ```
 
-When the URL is `/dashboard/settings`, Waymark renders `DashboardLayout` with `Settings` inside the outlet. The layout stays mounted (and doesn't even rerender) as users navigate between child routes, preserving any state it holds.
+When the URL is `/dashboard/settings`, Waymark renders `DashboardLayout` with `Settings` inside the outlet. The layout stays mounted (and doesn't even rerender) as users navigate between child routes.
 
 You can nest as deep as you need:
 
@@ -213,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:
 
@@ -229,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 when using `Link` or `navigate`. The intermediate routes still exist - they're 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.
 
@@ -251,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, or when you don't want to bother with `useRouter` / `useNavigate`:
+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";
@@ -281,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.
 
@@ -330,13 +339,183 @@ 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
+
+Dynamic segments in route patterns become typed path params. Define them with a colon prefix. They can also be made optional.
+
+```tsx
+const post = route("/posts/:id").component(PostPage);
+const comment = route("/posts/:postId/comments/:commentId?").component(
+  CommentPage
+);
+```
+
+Access parameters with `useParams`, passing the route pattern or object as an argument:
+
+```tsx
+function PostPage() {
+  const { id } = useParams(post);
+  // id is typed as string
+
+  const { id } = useParams("/posts/:id");
+  // Also works
+}
+
+function CommentPage() {
+  const { postId, commentId } = useParams(comment);
+  // postId: string
+  // commentId?: string | undefined
+}
+```
+
+Wildcard segments capture everything after a slash. They're defined with `*` and accessed with the key `"*"`:
+
+```tsx
+const files = route("/files/*").component(FileBrowser);
+
+function FileBrowser() {
+  const params = useParams(files);
+  const path = params["*"]; // e.g., "documents/report.pdf"
+}
+```
+
+---
+
+# Search params
+
+## 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 validation function.
+
+With Zod:
+
+```tsx
+import { z } from "zod";
+
+const searchPage = route("/search")
+  .search(
+    z.object({
+      q: z.string().catch(""),
+      page: z.coerce.number().catch(1)
+    })
+  )
+  .component(SearchPage);
+```
+
+With a plain function:
+
+```tsx
+const searchPage = route("/search")
+  .search(raw => ({
+    q: String(raw.q ?? ""),
+    page: Number(raw.page ?? 1)
+  }))
+  .component(SearchPage);
+```
+
+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() {
+  const [search, setSearch] = useSearch(searchPage);
+  // search.q: string
+  // search.page: number
+}
+```
+
+The setter merges your updates with existing values:
+
+```tsx
+setSearch({ page: 2 }); // Only updates page
+setSearch(prev => ({ page: prev.page + 1 })); // Increment page
+```
+
+Pass `true` as the second argument to replace the history entry instead of pushing:
+
+```tsx
+setSearch({ page: 1 }, true);
+```
+
+## 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 (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]`
+  - `42` → `count=42` → `42`
+
+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 is useful - it lets you transform these unknown values into a typed, validated shape that your components can safely use.
+
+## Inheritance
+
+When you define search params with a validator on a route, all child routes automatically inherit that validator along with its typing.
+
+Here's how it works. Start with a parent route that defines a search param:
+
+```tsx
+const dashboard = route("/dashboard")
+  .search(
+    z.object({
+      view: z.enum(["grid", "list"]).catch("grid")
+    })
+  )
+  .component(DashboardLayout);
+```
+
+Any child route created from `dashboard` inherits the `view` search param and its validation:
+
+```tsx
+const projects = dashboard.route("/projects").component(ProjectsPage);
+
+function ProjectsPage() {
+  const [search] = useSearch(projects);
+  // search.view is typed as "grid" | "list"
+}
+```
+
+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:
+
+```tsx
+const projects = dashboard
+  .route("/projects")
+  .search(
+    z.object({
+      status: z.enum(["active", "archived"]).catch("active")
+    })
+  )
+  .component(ProjectsPage);
+
+function ProjectsPage() {
+  const [search] = useSearch(projects);
+  // search.view: "grid" | "list" (from parent)
+  // search.status: "active" | "archived" (from child)
+}
+```
+
+## Idempotency requirement
+
+The validation function or schema you pass to `.search()` must be **idempotent**, meaning `fn(fn(x))` should equal `fn(x)`.
+
+When you read search params, the values are passed through your validator. When you update search params, the navigation APIs expect values in that same validated format, which are then JSON-encoded back into the URL. On the next read, those encoded values are decoded and passed through your validator again - meaning your validator may receive its own output as input.
 
 ---
 
-## 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:
 
@@ -385,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.
 
@@ -419,11 +598,13 @@ Or use the `activeClassName` and `activeStyle` props directly:
 </Link>
 ```
 
-### Link preloading
+## Route preloading
+
+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.
 
-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:
+The `preload` prop controls when preloading happens:
 
-**`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:
+**`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">
@@ -449,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
+<Link to="/heavy-page" preload="intent" preloadDelay={100}>
+  Heavy page
+</Link>
+```
+
+You can also preload programmatically using `router.preload()`:
 
 ```tsx
-userProfile.preload();
+const router = useRouter();
+router.preload({ to: userProfile, params: { id: "42" } });
 ```
 
-### Programmatic navigation
+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 (or `router.navigate`):
+For navigation triggered by code rather than user clicks, use the `useNavigate` hook:
 
 ```tsx
 import { useNavigate } from "waymark";
@@ -474,7 +666,7 @@ function LoginForm() {
 }
 ```
 
-The navigate function accepts the same options as `Link`:
+The navigate function accepts the same navigation options as `Link`:
 
 ```tsx
 navigate({ to: userProfile, params: { id: "42" }, search: { tab: "posts" } });
@@ -490,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:
+
+```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. external redirects):
+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:
 
@@ -521,7 +717,7 @@ function ProtectedPage() {
 }
 ```
 
-The `Navigate` component accepts the same props as the `Link` component, minus the visual and interaction properties. You can pass route patterns, params, search parameters, 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" }} />
@@ -533,186 +729,115 @@ Note that `Navigate` uses `useLayoutEffect` internally to ensure the navigation
 
 ---
 
-## Path parameters
+# Lazy loading
 
-Dynamic segments in route patterns become typed path parameters. Define them with a colon prefix. They can also be made optional.
+Load route components on demand with `.lazy()`. The function you pass should return a dynamic import:
 
 ```tsx
-const post = route("/posts/:id").component(PostPage);
-const comment = route("/posts/:postId/comments/:commentId?").component(
-  CommentPage
-);
+const analytics = route("/analytics").lazy(() => import("./AnalyticsPage"));
 ```
 
-Access parameters with `useParams`, passing the route pattern or object as an argument:
+The imported module should use a default export:
 
 ```tsx
-function PostPage() {
-  const { id } = useParams(post);
-  // id is typed as string
-
-  const { id } = useParams("/posts/:id");
-  // Also works
-}
-
-function CommentPage() {
-  const { postId, commentId } = useParams(comment);
-  // postId: string
-  // commentId?: string | undefined
-}
+// AnalyticsPage.tsx
+export default function AnalyticsPage() { ... }
 ```
 
-Wildcard segments capture everything after a slash. They're defined with `*` and accessed with the key `"*"`:
+If you're using a named export, you need to explicitly select which component to use by chaining `.then()` on the import:
 
 ```tsx
-const files = route("/files/*").component(FileBrowser);
+const analytics = route("/analytics").lazy(() =>
+  import("./AnalyticsPage").then(m => m.AnalyticsPage)
+);
 
-function FileBrowser() {
-  const params = useParams(files);
-  const path = params["*"]; // e.g., "documents/report.pdf"
-}
+// AnalyticsPage.tsx
+export function AnalyticsPage() { ... }
 ```
 
----
+Lazy routes work like any other route. Child routes inherit the parent's lazy-loaded components:
 
-## Search queries
+```tsx
+const dashboard = route("/dashboard").lazy(() => import("./Dashboard"));
+const settings = dashboard.route("/settings").component(Settings);
+```
 
-Search parameters (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://github.com/standard-schema/standard-schema) validator like Zod, or a plain mapping function.
+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.
 
-With Zod:
+See [Route preloading](#route-preloading) for ways to load these components before the user navigates.
 
-```tsx
-import { z } from "zod";
+---
 
-const searchPage = route("/search")
-  .search(
-    z.object({
-      q: z.string().catch(""),
-      page: z.coerce.number().catch(1)
-    })
-  )
-  .component(SearchPage);
-```
+# Data preloading
 
-With a plain function:
+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 searchPage = route("/search")
-  .search(raw => ({
-    q: String(raw.q ?? ""),
-    page: Number(raw.page ?? 1)
-  }))
-  .component(SearchPage);
+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);
 ```
 
-Access search params with `useSearch`, which returns a tuple of the current values and a setter function:
+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
-function SearchPage() {
-  const [search, setSearch] = useSearch(searchPage);
-  // search.q: string
-  // search.page: number
-}
+await queryClient.prefetchQuery({
+  queryKey: ["user", params.id],
+  queryFn: () => fetchUser(params.id),
+  staleTime: 60_000 // No refetch within 60s
+});
 ```
 
-The setter merges your updates with existing values:
+Preload functions inherit to child routes:
 
 ```tsx
-setSearch({ page: 2 }); // Only updates page
-setSearch(prev => ({ page: prev.page + 1 })); // Increment page
+const dashboard = route("/dashboard")
+  .preload(prefetchDashboardData)
+  .component(DashboardLayout);
+
+const settings = dashboard.route("/settings").component(Settings);
+// Preloading /dashboard/settings runs prefetchDashboardData
 ```
 
-Pass `true` as the second argument to replace the history entry instead of pushing:
+---
 
-```tsx
-setSearch({ page: 1 }, true);
-```
+# Error boundaries
 
-**JSON-first search params**
+Catch errors thrown during rendering with `.error()`. The error component receives the error as a prop:
 
-Waymark uses a JSON-first approach for search parameters, similar to TanStack Router. When serializing and deserializing values from the URL:
+```tsx
+const fragile = route("/fragile").error(ErrorFallback).component(FragilePage);
 
-- Plain strings that aren't valid JSON are kept as-is: `"John"` → `?name=John` → `"John"`
-- Everything else is JSON-encoded (and URL-encoded):
-  - `true` → `?enabled=true` → `true`
-  - `"true"` → `?enabled=%22true%22` → `"true"`
-  - `[1, 2]` → `?filters=%5B1%2C2%5D` → `[1, 2]`
-  - `42` → `count=42` → `42`
+function ErrorFallback({ error }: { error: unknown }) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <pre>{String(error)}</pre>
+      <button onClick={() => window.location.reload()}>Retry</button>
+    </div>
+  );
+}
+```
 
-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.
+Error boundaries catch errors from all nested content. A common pattern is to place one at the root to catch any unhandled errors:
+
+```tsx
+const app = route("/").error(ErrorPage).component(AppLayout);
+```
 
-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.
+To give new routes a fresh start, the error boundary automatically resets when navigation occurs.
 
 ---
 
-## Lazy loading
-
-Load route components on demand with `.lazy()`. The function you pass should return a dynamic import:
-
-```tsx
-const analytics = route("/analytics").lazy(() => import("./AnalyticsPage"));
-```
-
-The imported module should use a default export:
-
-```tsx
-// AnalyticsPage.tsx
-export default function AnalyticsPage() { ... }
-```
-
-If you're using a named export, you need to explicitly select which component to use by chaining `.then()` on the import:
-
-```tsx
-const analytics = route("/analytics").lazy(() =>
-  import("./AnalyticsPage").then(m => m.AnalyticsPage)
-);
-
-// AnalyticsPage.tsx
-export function AnalyticsPage() { ... }
-```
-
-Lazy routes work seamlessly with nesting. Child routes inherit the lazy-loaded parent's components:
-
-```tsx
-const dashboard = route("/dashboard").lazy(() => import("./Dashboard"));
-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.
-
----
-
-## Error boundaries
-
-Catch errors thrown during rendering with `.error()`. The error component receives the error as a prop:
-
-```tsx
-const fragile = route("/fragile").error(ErrorFallback).component(FragilePage);
-
-function ErrorFallback({ error }: { error: unknown }) {
-  return (
-    <div>
-      <h2>Something went wrong</h2>
-      <pre>{String(error)}</pre>
-      <button onClick={() => window.location.reload()}>Retry</button>
-    </div>
-  );
-}
-```
-
-Error boundaries catch errors from all nested content. A common pattern is to place one at the root to catch any unhandled errors:
-
-```tsx
-const app = route("/").error(ErrorPage).component(AppLayout);
-```
-
-The error boundary automatically resets when navigation occurs, giving the new route a fresh start.
-
----
-
-## 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()`:
 
@@ -741,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.
 
@@ -767,8 +892,8 @@ function Breadcrumbs() {
     <nav>
       {handles.map((h, i) => (
         <span key={i}>
+          {i !== 0 && " / "}
           {h.title}
-          {i < handles.length - 1 && " / "}
         </span>
       ))}
     </nav>
@@ -791,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.
 
@@ -843,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.
 
@@ -865,7 +990,7 @@ import { HashHistory } from "waymark";
 <RouterRoot routes={routes} history={new HashHistory()} />;
 ```
 
-**MemoryHistory** keeps the history in memory without touching the URL. It also doesn't rely on any browser API. Perfect for testing, server-side rendering, or embedded applications:
+**MemoryHistory** keeps the history in memory without touching the URL. It also doesn't rely on any browser API. Perfect for testing, server-side rendering (SSR), or embedded applications:
 
 ```tsx
 import { MemoryHistory } from "waymark";
@@ -877,9 +1002,94 @@ All history implementations conform to the `HistoryLike` interface, so you can c
 
 ---
 
-## Cookbook
+# Cookbook
+
+## Quick start example
+
+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
+import { renderToString } from "react-dom/server";
+import { RouterRoot, MemoryHistory, type SSRContext } from "waymark";
+import { routes } from "./routes";
+
+function handleRequest(req: Request) {
+  const ssrContext: SSRContext = {};
+  const html = renderToString(
+    <RouterRoot
+      routes={routes}
+      history={new MemoryHistory(req.url)}
+      ssrContext={ssrContext}
+    />
+  );
+  if (ssrContext.redirect) {
+    return Response.redirect(ssrContext.redirect);
+  }
+  return new Response(html, {
+    headers: { "Content-Type": "text/html" }
+  });
+}
+```
 
-### Scroll to top on navigation
+The `ssrContext` object captures information during server rendering. When a `Navigate` component renders on the server (typically from conditional logic), it populates `ssrContext.redirect` with the target URL. Your server can then return an HTTP redirect instead of the rendered HTML.
+
+On the client, use the default (`BrowserHistory`) for hydration:
+
+```tsx
+// client.tsx
+import { hydrateRoot } from "react-dom/client";
+import { RouterRoot } from "waymark";
+import { routes } from "./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).
+
+## Scroll to top on navigation
 
 Create a component that scrolls to top when the path changes and include it in your layout:
 
@@ -904,15 +1114,57 @@ 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`.
 
-Set defaults for all `Link` components using `defaultLinkOptions` on the router. This is useful for consistent styling and preload behavior across your app:
+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:
 
 ```tsx
 <RouterRoot
   routes={routes}
   defaultLinkOptions={{
     preload: "intent",
+    preloadDelay: 75,
     className: "app-link",
     activeClassName: "active"
   }}
@@ -921,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:
 
@@ -960,9 +1212,9 @@ const router = new Router({
 });
 ```
 
-### View transitions
+## View transitions
 
-Use the View Transitions API for smoother page animations. Create a history middleware that wraps navigation in a view transition:
+You can use the view transitions API for smoother page animations. Create a history middleware that wraps navigation in a view transition:
 
 ```tsx
 import { flushSync } from "react-dom";
@@ -1000,132 +1252,37 @@ 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
-
-### Types
-
-**`NavigateOptions<P>`** is the main type 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
-  state?: any; // Arbitrary state to pass
-};
-```
-
-**`HistoryPushOptions`** is for untyped navigation:
-
-```tsx
-interface HistoryPushOptions {
-  url: string; // The URL to navigate to
-  replace?: boolean; // Replace history instead of push
-  state?: any; // Arbitrary state to pass
-}
-```
-
-**`MatchOptions<P>`** is used 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>>; // Filter by specific param values
-};
-```
-
-**`Match<P>`** is the result of a successful match:
+# API reference
 
-```tsx
-type Match<P extends Pattern> = {
-  route: Route<P>; // The matched route
-  params: Params<P>; // Extracted parameters
-};
-```
-
-**`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;
-}
-```
-
-### 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({
-  routes: Route[], // Required: array of routes
-  basePath: string, // Optional: base path prefix (default: "/")
-  history: HistoryLike, // Optional: history implementation (default: BrowserHistory)
-  defaultLinkOptions: LinkOptions // Optional: defaults for all Links
-});
-```
-
 **Properties:**
 
 - `router.basePath` - The configured base path
 - `router.routes` - The array of routes
 - `router.history` - The history instance
+- `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
@@ -1139,103 +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.
 
-```tsx
-const route = router.getRoute("/users/:id");
-```
-
-### History interface
-
-The `History` interface defines how Waymark interacts with navigation. All history implementations conform to this interface.
-
-**Interface:**
+- `pattern` - `Pattern | Route` - A route pattern string or a route object
+- Returns: `Route` - The route object; throws if not found
 
 ```tsx
-interface HistoryLike {
-  getPath: () => string;
-  getSearch: () => Record<string, unknown>;
-  getState: () => any;
-  go: (delta: number) => void;
-  push: (options: HistoryPushOptions) => void;
-  subscribe: (listener: () => void) => () => void;
-}
-```
-
-**Methods:**
-
-`history.getPath()` returns the current pathname:
-
-```tsx
-const path = history.getPath();
-// Returns "/users/42"
-```
-
-`history.getSearch()` returns the current search parameters as a parsed object:
-
-```tsx
-const search = history.getSearch();
-// Returns { tab: "posts", page: 2 }
-```
-
-`history.getState()` returns the current history state:
-
-```tsx
-const state = history.getState();
-// Returns any state passed during navigation
+const route = router.getRoute("/users/:id");
 ```
 
-`history.go(delta)` navigates forward or back in history:
+**`router.preload(options)`** triggers preloading for a route.
 
-```tsx
-history.go(-1); // Go back
-history.go(1); // Go forward
-history.go(-2); // Go back two steps
-```
-
-`history.push(options)` pushes or replaces a history entry:
+- `options` - `NavigateOptions` - Type-safe navigation options
+- Returns: `Promise<void>` - Resolves when preloaded
 
 ```tsx
-history.push({ url: "/users/42", state: { from: "list" } });
-history.push({ url: "/login", replace: true });
-```
-
-`history.subscribe(listener)` subscribes to navigation events and returns an unsubscribe function:
-
-```tsx
-const unsubscribe = history.subscribe(() => {
-  console.log("Navigation occurred");
-});
-
-// Later: unsubscribe()
+await router.preload({ to: "/user/:id", params: { id: "42" } });
+await router.preload({ to: searchPage, search: { q: "test" } });
 ```
 
-### Route class
+## 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");
@@ -1243,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")
@@ -1282,35 +1424,42 @@ 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:
-
-```tsx
-const users = route("/users").preloader(async () => {
-  await prefetchData();
-});
-```
+**`.preload(preload)`** registers a preload function for the route.
 
-**`.preload()`** manually triggers all registered preloaders (including lazy component loading):
+- `preload` - `(context: PreloadContext) => Promise<any>` - An async function receiving typed `params` and `search`
+- Returns: `Route` - A new route object
 
 ```tsx
-await userProfile.preload();
+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);
+  });
 ```
 
-### Hooks
+## Hooks
+
+**`useRouter()`** returns the Router instance from context.
 
-**`useRouter()`** returns the Router instance:
+- Returns: `Router` - The router instance
 
 ```tsx
 const router = useRouter();
 ```
 
-**`useNavigate()`** returns a navigation function:
+**`useNavigate()`** returns a navigation function.
+
+- Returns: `(options: NavigateOptions | HistoryPushOptions | number) => void` - The navigate function
 
 ```tsx
 const navigate = useNavigate();
@@ -1318,34 +1467,47 @@ navigate({ to: "/home" });
 navigate(-1);
 ```
 
-**`useLocation()`** returns the current location:
+**`useLocation()`** returns the current location, subscribes to changes.
+
+- Returns: `{ path: string, search: Record<string, unknown>, state: any }` - The current path, parsed search params, and history state
 
 ```tsx
 const { path, search, state } = useLocation();
-// path: string, search: Record<string, unknown>, state: any
 ```
 
-**`useOutlet()`** returns the nested route content (used internally by `Outlet`):
+**`useOutlet()`** returns the child route content.
+
+- Returns: `ReactNode` - The child route's content or null
 
 ```tsx
 const outlet = useOutlet();
 ```
 
-**`useParams(route)`** returns typed parameters for a route:
+**`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 { id } = useParams(userRoute);
 ```
 
-**`useSearch(route)`** returns search params and a setter:
+**`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
 const [search, setSearch] = useSearch(searchRoute);
 setSearch({ page: 2 });
 setSearch(prev => ({ page: prev.page + 1 }));
+setSearch({ page: 1 }, true); // Replace instead of push
 ```
 
-**`useMatch(options)`** checks if a route matches the current path:
+**`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
 const match = useMatch({ from: "/users/:id" });
@@ -1353,22 +1515,26 @@ const strictMatch = useMatch({ from: "/users", strict: true });
 const filteredMatch = useMatch({ from: "/users/:id", params: { id: "admin" } });
 ```
 
-**`useHandles()`** returns all handles from the matched route chain in order:
+**`useHandles()`** returns the handles from the matched route chain.
+
+- Returns: `Handle[]` - Array of handles
 
 ```tsx
 const handles = useHandles();
 ```
 
-### Components
+## Components
+
+**`RouterRoot`** sets up routing context and renders your routes.
 
-**`RouterRoot`** is the root provider. Pass either router options or a router instance:
+- `props` - `RouterOptions | { router: Router }` - Either router options (same as the `Router` constructor) or a router instance
 
 ```tsx
 <RouterRoot routes={routes} basePath="/app" history={history} />
 <RouterRoot router={router} />
 ```
 
-**`Outlet`** renders child route content:
+**`Outlet`** renders the child route content.
 
 ```tsx
 function Layout() {
@@ -1380,7 +1546,9 @@ function Layout() {
 }
 ```
 
-**`Link`** navigates on click. Props extend `NavigateOptions` and `LinkOptions`:
+**`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
 <Link to="/path" params={...} search={...} replace strict preload="intent">
@@ -1388,23 +1556,187 @@ function Layout() {
 </Link>
 ```
 
-**`Navigate`** redirects on render. Props are `NavigateOptions`:
+**`Navigate`** redirects on render.
+
+- `props` - `NavigateOptions` - The navigation target
 
 ```tsx
 <Navigate to="/login" replace />
 ```
 
----
+## History interface
+
+The `HistoryLike` interface defines how Waymark interacts with navigation. All history implementations conform to this interface.
 
-## Roadmap
+**Available implementations:**
+
+```tsx
+new BrowserHistory(); // Browser History API (/posts/123). Default.
+new HashHistory(); // URL hash (/#/posts/123).
+new MemoryHistory("/initial"); // In-memory only.
+```
+
+See [History implementations](#history-implementations) for detailed usage.
+
+**`history.getPath()`** returns the current path.
+
+- Returns: `string` - The current path
+
+```tsx
+const path = history.getPath();
+// Returns "/users/42"
+```
+
+**`history.getSearch()`** returns the current search params as a parsed JSON object.
+
+- Returns: `Record<string, unknown>` - The parsed search params
+
+```tsx
+const search = history.getSearch();
+// Returns { tab: "posts", page: 2 }
+```
+
+**`history.getState()`** returns the current history state.
+
+- Returns: `any` - The state passed during navigation, or undefined
+
+```tsx
+const state = history.getState();
+// Returns any state passed during navigation
+```
+
+**`history.go(delta)`** navigates forward or back in history.
+
+- `delta` - `number` - The number of entries to move
+- Returns: `void`
+
+```tsx
+history.go(-1); // Go back
+history.go(1); // Go forward
+history.go(-2); // Go back two steps
+```
+
+**`history.push(options)`** pushes or replaces a history entry.
+
+- `options` - `HistoryPushOptions` - The URL to navigate to, with optional `replace` and `state`
+- Returns: `void`
+
+```tsx
+history.push({ url: "/users/42", state: { from: "list" } });
+history.push({ url: "/login", replace: true });
+```
+
+**`history.subscribe(listener)`** subscribes to navigation events.
+
+- `listener` - `() => void` - Callback invoked when any navigation occurs
+- Returns: `() => void` - An unsubscribe function
+
+```tsx
+const unsubscribe = history.subscribe(() => {
+  console.log("Navigation occurred");
+});
+
+// Later: unsubscribe()
+```
+
+## Types
+
+**`RouterOptions`** are options for creating a `Router` instance or passing to `RouterRoot`.
+
+```tsx
+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
+}
+```
+
+**`NavigateOptions`** are options for type-safe navigation.
+
+```tsx
+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`** are options for untyped navigation.
+
+```tsx
+interface HistoryPushOptions {
+  url: string; // The URL to navigate to
+  replace?: boolean; // Replace history entry instead of pushing
+  state?: any; // Arbitrary state to pass
+}
+```
+
+**`MatchOptions`** are options for route matching.
+
+```tsx
+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`** is the result of a successful route match.
+
+```tsx
+type Match = {
+  route: Route; // Matched route object
+  params: Params; // Extracted path params
+};
+```
+
+**`LinkOptions`** controls link behavior and styling.
+
+```tsx
+interface LinkOptions {
+  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 server-side rendering.
+
+```tsx
+type SSRContext = {
+  redirect?: string; // Set by Navigate component during SSR
+  statusCode?: number; // Can be set manually for HTTP status
+};
+```
+
+**`PreloadContext`** is the context passed to preload functions.
+
+```tsx
+interface PreloadContext {
+  params: Params; // Path params for the route
+  search: Search; // Validated search params
+}
+```
+
+---
 
-Future improvements planned for Waymark:
+# Roadmap
 
-- **Preloader context** - Pass route params and search queries to preloader functions, enabling data fetching based on the target route's dynamic segments
-- **Server-side rendering guide** - Add documentation for using Waymark in SSR environments
+- 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