waymark 0.2.1 → 0.2.3

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,23 +8,25 @@
 
 <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
 
 ---
@@ -37,20 +39,25 @@ 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)
   - [Programmatic navigation](#programmatic-navigation)
   - [Declarative navigation](#declarative-navigation)
-- [Path parameters](#path-parameters)
-- [Search queries](#search-queries)
 - [Lazy loading](#lazy-loading)
 - [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)
   - [Scroll to top on navigation](#scroll-to-top-on-navigation)
   - [Global link configuration](#global-link-configuration)
@@ -58,12 +65,12 @@ Waymark is a routing library for React built around three core ideas: **type saf
   - [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)
+  - [History interface](#history-interface)
   - [Hooks](#hooks)
   - [Components](#components)
+  - [Types](#types)
 - [Roadmap](#roadmap)
 - [License](#license)
 
@@ -106,7 +113,7 @@ 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.
 
 ---
 
@@ -189,7 +196,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:
 
@@ -229,7 +236,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 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.
 
 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 +258,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 is useful when you need to access the router from anywhere in your code, for example to navigate programmatically from a non-React context:
 
 ```tsx
 import { Router, RouterRoot } from "waymark";
@@ -334,6 +341,174 @@ But again, this is just one approach. You could keep all routes in a single file
 
 ---
 
+## 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 mapping 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);
+```
+
+Access 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: `"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`
+
+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.
+
+### 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 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.
+
+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
 
 ### The Link component
@@ -457,7 +632,7 @@ userProfile.preload();
 
 ### Programmatic navigation
 
-For navigation triggered by code rather than user clicks, use the `useNavigate` hook:
+For navigation triggered by code rather than user clicks, use the `useNavigate` hook (or `router.navigate`):
 
 ```tsx
 import { useNavigate } from "waymark";
@@ -474,7 +649,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" } });
@@ -495,14 +670,12 @@ You can also access the router directly via `useRouter()` (or import the router
 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
-const router = useRouter();
-
 // Type-safe navigation
-router.navigate({ to: userProfile, params: { id: "42" } });
+navigate({ to: userProfile, params: { id: "42" } });
 
 // Unsafe navigation - no type checking
-router.navigate({ url: "/some/unknown/path" });
-router.navigate({ url: "/callback", replace: true, state: { data: 123 } });
+navigate({ url: "/some/unknown/path" });
+navigate({ url: "/callback", replace: true, state: { data: 123 } });
 ```
 
 ### Declarative navigation
@@ -523,7 +696,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. You can pass route patterns, path params, search params, and state:
 
 ```tsx
 <Navigate to="/users/:id" params={{ id: "42" }} search={{ tab: "posts" }} />
@@ -535,118 +708,6 @@ Note that `Navigate` uses `useLayoutEffect` internally to ensure the navigation
 
 ---
 
-## Path parameters
-
-Dynamic segments in route patterns become typed path parameters. 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 queries
-
-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.
-
-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);
-```
-
-Access 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 search params**
-
-Waymark uses a JSON-first approach for search parameters, 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):
-  - `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 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.
-
----
-
 ## Lazy loading
 
 Load route components on demand with `.lazy()`. The function you pass should return a dynamic import:
@@ -673,7 +734,7 @@ const analytics = route("/analytics").lazy(() =>
 export function AnalyticsPage() { ... }
 ```
 
-Lazy routes work seamlessly with nesting. Child routes inherit the lazy-loaded parent's components:
+Lazy routes work like any other route. Child routes inherit the parent's lazy-loaded components:
 
 ```tsx
 const dashboard = route("/dashboard").lazy(() => import("./Dashboard"));
@@ -867,7 +928,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";
@@ -879,17 +940,64 @@ All history implementations conform to the `HistoryLike` interface, so you can c
 
 ---
 
-## Cookbook
+## Server-side rendering (SSR)
 
-### Scroll to top on navigation
+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.
 
-Create a component that scrolls to top when the path changes and include it in your layout:
+On the server, create a router with `MemoryHistory` initialized to the request URL:
 
 ```tsx
-import { useLocation } from "waymark";
-import { useEffect } from "react";
+// server.tsx
+import { renderToString } from "react-dom/server";
+import { RouterRoot, MemoryHistory, type SSRContext } from "waymark";
+import { routes } from "./routes";
 
-function ScrollToTop() {
+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" }
+  });
+}
+```
+
+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(document.getElementById("root")!, <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
+
+Create a component that scrolls to top when the path changes and include it in your layout:
+
+```tsx
+import { useLocation } from "waymark";
+import { useEffect } from "react";
+
+function ScrollToTop() {
   const { path } = useLocation();
   useEffect(() => window.scrollTo(0, 0), [path]);
   return null;
@@ -908,7 +1016,7 @@ function AppLayout() {
 
 ### Global link configuration
 
-Set defaults for all `Link` components using `defaultLinkOptions` on the router. This is useful for consistent styling and preload behavior across your app:
+Set defaults for all `Link` components using `defaultLinkOptions` on the router. Useful for consistent styling and preload behavior across your app:
 
 ```tsx
 <RouterRoot
@@ -964,7 +1072,7 @@ const router = new Router({
 
 ### 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";
@@ -1047,62 +1155,6 @@ if (adminMatch) {
 
 ## 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:
-
-```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
 
 The `Router` class is the core of Waymark. You can create an instance directly or let `RouterRoot` create one.
@@ -1111,9 +1163,10 @@ The `Router` class is the core of Waymark. You can create an instance directly o
 
 ```tsx
 const router = new Router({
-  routes: Route[], // Required: array of routes
   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
 });
 ```
@@ -1123,6 +1176,7 @@ const router = new Router({
 - `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:**
@@ -1168,71 +1222,6 @@ const match = router.matchAll("/users/42");
 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:**
-
-```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
-```
-
-`history.go(delta)` navigates forward or back in history:
-
-```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:
-
-```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()
-```
-
 ### Route class
 
 Routes are created with the `route()` function and configured by chaining methods.
@@ -1304,6 +1293,71 @@ const users = route("/users").preloader(async () => {
 await userProfile.preload();
 ```
 
+### History interface
+
+The `History` interface defines how Waymark interacts with navigation. All history implementations conform to this interface.
+
+**Interface:**
+
+```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 params 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
+```
+
+`history.go(delta)` navigates forward or back in history:
+
+```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:
+
+```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()
+```
+
 ### Hooks
 
 **`useRouter()`** returns the Router instance:
@@ -1396,14 +1450,78 @@ function Layout() {
 <Navigate to="/login" replace />
 ```
 
+### 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>>; // Match by specific param values
+};
+```
+
+**`Match<P>`** is the result of a successful match:
+
+```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;
+}
+```
+
+**`SSRContext`** captures context during SSR (like redirects):
+
+```tsx
+type SSRContext = {
+  redirect?: string; // Set by Navigate component during SSR
+  statusCode?: number; // Can be set manually in your components during SSR
+};
+```
+
 ---
 
 ## Roadmap
 
 Future improvements planned for Waymark:
 
-- **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
+- **Preloader context** - Pass path params and search params to preloader functions, enabling loading logic based on the target route's dynamic data
 
 ---
 

package/dist/index.d.ts

@@ -39,6 +39,10 @@ type NavigateOptions<P extends Pattern> = {
   replace?: boolean;
   state?: any;
 } & MaybeKey<"params", Params<P>> & MaybeKey<"search", Search<P>>;
+type SSRContext = {
+  redirect?: string;
+  statusCode?: number;
+};
 interface HistoryPushOptions {
   url: string;
   replace?: boolean;
@@ -76,7 +80,7 @@ declare class Route<P extends string = string, Ps extends {} = any, S extends {}
   };
   constructor(pattern: P, mapSearch: (search: Record<string, unknown>) => S, handles: Handle[], components: ComponentType[], preloaders: (() => Promise<any>)[]);
   route<P2 extends string>(subPattern: P2): Route<NormalizePath<`${P}/${P2}`>, regexparam0.RouteParams<NormalizePath<`${P}/${P2}`>> extends infer T ? { [KeyType in keyof T]: T[KeyType] } : never, S>;
-  search<S2 extends {}>(mapper: ((search: S & Record<string, unknown>) => S2) | StandardSchemaV1<S & Record<string, unknown>, S2>): Route<P, Ps, (type_fest0.PickIndexSignature<S> extends infer T_1 ? { [Key in keyof T_1 as Key extends keyof type_fest0.PickIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_2 ? { [KeyType_1 in keyof T_2]: T_2[KeyType_1] } : never> ? never : Key]: T_1[Key] } : never) & type_fest0.PickIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_2 ? { [KeyType_1 in keyof T_2]: T_2[KeyType_1] } : never> & (type_fest0.OmitIndexSignature<S> extends infer T_3 ? { [Key_1 in keyof T_3 as Key_1 extends keyof type_fest0.OmitIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_4 ? { [KeyType_1 in keyof T_4]: T_4[KeyType_1] } : never> ? never : Key_1]: T_3[Key_1] } : never) & type_fest0.OmitIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_4 ? { [KeyType_1 in keyof T_4]: T_4[KeyType_1] } : never> extends infer T ? { [KeyType in keyof T]: T[KeyType] } : never>;
+  search<S2 extends {}>(mapper: ((search: S & Record<string, unknown>) => S2) | StandardSchemaV1<Record<string, unknown>, S2>): Route<P, Ps, (type_fest0.PickIndexSignature<S> extends infer T_1 ? { [Key in keyof T_1 as Key extends keyof type_fest0.PickIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_2 ? { [KeyType_1 in keyof T_2]: T_2[KeyType_1] } : never> ? never : Key]: T_1[Key] } : never) & type_fest0.PickIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_2 ? { [KeyType_1 in keyof T_2]: T_2[KeyType_1] } : never> & (type_fest0.OmitIndexSignature<S> extends infer T_3 ? { [Key_1 in keyof T_3 as Key_1 extends keyof type_fest0.OmitIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_4 ? { [KeyType_1 in keyof T_4]: T_4[KeyType_1] } : never> ? never : Key_1]: T_3[Key_1] } : never) & type_fest0.OmitIndexSignature<{ [K in keyof S2 as undefined extends S2[K] ? never : K]: S2[K] } & { [K_1 in keyof S2 as undefined extends S2[K_1] ? K_1 : never]?: S2[K_1] | undefined } extends infer T_4 ? { [KeyType_1 in keyof T_4]: T_4[KeyType_1] } : never> extends infer T ? { [KeyType in keyof T]: T[KeyType] } : never>;
   handle(handle: Handle): Route<P, Ps, S>;
   preloader(preloader: () => Promise<any>): Route<P, Ps, S>;
   component(component: ComponentType): Route<P, Ps, S>;
@@ -135,12 +139,14 @@ interface RouterOptions {
   basePath?: string;
   routes: RouteList;
   history?: HistoryLike;
+  ssrContext?: SSRContext;
   defaultLinkOptions?: LinkOptions;
 }
 declare class Router {
   readonly basePath: string;
   readonly routes: RouteList;
   readonly history: HistoryLike;
+  readonly ssrContext?: SSRContext;
   readonly defaultLinkOptions?: LinkOptions;
   private readonly _;
   constructor(options: RouterOptions);
@@ -193,4 +199,4 @@ declare class HashHistory extends BrowserHistory {
   push: (options: HistoryPushOptions) => void;
 }
 //#endregion
-export { BrowserHistory, ComponentLoader, GetRoute, Handle, HashHistory, HistoryLike, HistoryPushOptions, Link, LinkOptions, LinkProps, Match, MatchContext, MatchOptions, MemoryHistory, MemoryLocation, Navigate, NavigateOptions, NavigateProps, Outlet, OutletContext, Params, Pattern, Register, Route, RouteList, Router, RouterContext, RouterOptions, RouterRoot, RouterRootProps, Search, Updater, route, useHandles, useLocation, useMatch, useNavigate, useOutlet, useParams, useRouter, useSearch, useSubscribe };
+export { BrowserHistory, ComponentLoader, GetRoute, Handle, HashHistory, HistoryLike, HistoryPushOptions, Link, LinkOptions, LinkProps, Match, MatchContext, MatchOptions, MemoryHistory, MemoryLocation, Navigate, NavigateOptions, NavigateProps, Outlet, OutletContext, Params, Pattern, Register, Route, RouteList, Router, RouterContext, RouterOptions, RouterRoot, RouterRootProps, SSRContext, Search, Updater, route, useHandles, useLocation, useMatch, useNavigate, useOutlet, useParams, useRouter, useSearch, useSubscribe };

package/dist/index.js

@@ -1 +1 @@
-import{Component as e,Suspense as t,cloneElement as n,createContext as r,isValidElement as i,lazy as a,memo as o,useCallback as s,useContext as c,useEffect as ee,useLayoutEffect as l,useMemo as u,useRef as d,useState as f,useSyncExternalStore as p}from"react";import{inject as m,parse as h}from"regexparam";import{jsx as g}from"react/jsx-runtime";function _(e){return`/${e}`.replaceAll(/\/+/g,`/`).replace(/(.+)\/$/,`$1`)}function v(e){return e.split(`/`).slice(1).map(e=>e.includes(`*`)?0:e.includes(`:`)?1:2)}function y(e){return typeof e==`function`?e:t=>{let n=e[`~standard`].validate(t);if(n instanceof Promise)throw Error(`[Waymark] Validation must be synchronous`);if(n.issues)throw Error(`[Waymark] Validation failed`,{cause:n.issues});return n.value}}function b(e){return Object.entries(e).filter(([e,t])=>t!==void 0).map(([e,t])=>`${e}=${encodeURIComponent(S(t))}`).join(`&`)}function x(e){let t=new URLSearchParams(e);return Object.fromEntries([...t.entries()].map(([e,t])=>(t=decodeURIComponent(t),[e,C(t)?JSON.parse(t):t])))}function S(e){return typeof e==`string`&&!C(e)?e:JSON.stringify(e)}function C(e){try{return JSON.parse(e),!0}catch{return!1}}function w(e,t){return _(`${t}/${e}`)}function T(e,t){return(e===t||e.startsWith(`${t}/`))&&(e=e.slice(t.length)||`/`),e}function E(e,t){return[e,b(t)].filter(Boolean).join(`?`)}function D(e){let{pathname:t,search:n}=new URL(e,`http://w`);return{path:t,search:x(n)}}function O(e,t,n,r){let i=e.exec(T(n,r));if(!i)return null;let a={};return t.forEach((e,t)=>{let n=i[t+1];n&&(a[e]=n)}),a}function k(e){return[...e].sort((e,t)=>{let n=e.route._.weights,r=t.route._.weights,i=Math.max(n.length,r.length);for(let e=0;e<i;e++){let t=n[e]??-1,i=r[e]??-1;if(t!==i)return i-t}return 0})}const A=r(null),j=r(null),M=r(null);function N(){let e=c(A);if(!e)throw Error(`[Waymark] useRouter must be used within a router context`);return e}function P(){let e=c(j);return u(()=>e?.route._.handles??[],[e])}function F(){return c(M)}function I(e,t){return p(e.history.subscribe,t,t)}function L(){let e=N();return u(()=>e.navigate.bind(e),[e])}function te(){let e=N(),t=I(e,e.history.getPath),n=I(e,e.history.getSearch),r=I(e,e.history.getState);return u(()=>({path:t,search:n,state:r}),[t,n,r])}function R(e){let t=N(),n=I(t,t.history.getPath);return u(()=>t.match(n,e),[t,n,e])}function z(e){let t=R({from:e});if(!t)throw Error(`[Waymark] Can't read params for non-matching route: ${e}`);return t.params}function B(e){let t=N(),n=t.getRoute(e),r=s(e=>n._.mapSearch(e),[n]),i=I(t,t.history.getSearch);return[u(()=>r(i),[r,i]),s((e,n)=>{let i=r(t.history.getSearch());e=typeof e==`function`?e(i):e;let a=E(t.history.getPath(),{...i,...e});t.navigate({url:a,replace:n})},[t,r])]}var V=class e{static patchKey=Symbol.for(`waymark_history_patch_v01`);memo;constructor(){if(typeof history<`u`&&!(e.patchKey in window)){for(let e of[H,U]){let t=history[e];history[e]=function(...n){let r=t.apply(this,n),i=new Event(e);return i.arguments=n,dispatchEvent(i),r}}window[e.patchKey]=!0}}getSearchMemo=e=>this.memo?.search===e?this.memo.parsed:(this.memo={search:e,parsed:x(e)}).parsed;getPath=()=>location.pathname;getSearch=()=>this.getSearchMemo(location.search);getState=()=>history.state;go=e=>history.go(e);push=e=>{let{url:t,replace:n,state:r}=e;history[n?U:H](r,``,t)};subscribe=e=>(W.forEach(t=>window.addEventListener(t,e)),()=>{W.forEach(t=>window.removeEventListener(t,e))})};const H=`pushState`,U=`replaceState`,W=[`popstate`,H,U,`hashchange`];var G=class{basePath;routes;history;defaultLinkOptions;_;constructor(e){let{basePath:t=`/`,routes:n,history:r,defaultLinkOptions:i}=e;this.basePath=_(t),this.routes=n,this.history=r??new V,this.defaultLinkOptions=i,this._={routeMap:new Map(n.map(e=>[e.pattern,e]))}}getRoute(e){if(typeof e!=`string`)return e;let t=this._.routeMap.get(e);if(!t)throw Error(`[Waymark] Route not found for pattern: ${e}`);return t}match(e,t){let{from:n,strict:r,params:i}=t,a=this.getRoute(n),o=O(r?a._.regex:a._.looseRegex,a._.keys,e,this.basePath);return!o||i&&Object.keys(i).some(e=>i[e]!==o[e])?null:{route:a,params:o}}matchAll(e){return k(this.routes.map(t=>this.match(e,{from:t,strict:!0})).filter(e=>!!e))[0]??null}createUrl(e){let{to:t,params:n={},search:r={}}=e,{pattern:i}=this.getRoute(t);return E(w(m(i,n),this.basePath),r)}navigate(e){if(typeof e==`number`)this.history.go(e);else if(`url`in e)this.history.push(e);else{let{replace:t,state:n}=e;this.history.push({url:this.createUrl(e),replace:t,state:n})}}},K=class{stack=[];index=0;listeners=new Set;constructor(e=`/`){this.stack.push({...D(e),state:void 0})}getCurrent=()=>this.stack[this.index];getPath=()=>this.getCurrent().path;getSearch=()=>this.getCurrent().search;getState=()=>this.getCurrent().state;go=e=>{let t=this.index+e;this.stack[t]&&(this.index=t,this.listeners.forEach(e=>e()))};push=e=>{let{url:t,replace:n,state:r}=e,i={...D(t),state:r};this.stack=this.stack.slice(0,this.index+1),n?this.stack[this.index]=i:this.index=this.stack.push(i)-1,this.listeners.forEach(e=>e())};subscribe=e=>(this.listeners.add(e),()=>{this.listeners.delete(e)})},q=class extends V{getHashUrl=()=>new URL(location.hash.slice(1),`http://w`);getPath=()=>this.getHashUrl().pathname;getSearch=()=>this.getSearchMemo(this.getHashUrl().search);push=e=>{let{url:t,replace:n,state:r}=e;history[n?`replaceState`:`pushState`](r,``,`#${t}`)}};function J(e){let[t]=f(()=>`router`in e?e.router:new G(e)),n=I(t,t.history.getPath),r=u(()=>t.matchAll(n),[t,n]);return r||console.error(`[Waymark] No matching route found for path:`,n),u(()=>g(A.Provider,{value:t,children:g(j.Provider,{value:r,children:r?.route._.components.reduceRight((e,t)=>g(M.Provider,{value:e,children:g(t,{})}),null)})}),[t,r])}function Y(){return F()}function X(e){let t=L();return l(()=>t(e),[]),null}function Z(e){let t=N(),{to:r,replace:a,state:o,params:s,search:c,strict:l,preload:f,style:p,className:m,activeStyle:h,activeClassName:_,asChild:v,children:y,...b}={...t.defaultLinkOptions,...e},x=d(null),S=t.createUrl(e),C=u(()=>t.getRoute(e.to),[t,e.to]),w=!!R({from:C,strict:l,params:s}),T=u(()=>({"data-active":w,style:{...p,...w&&h},className:[m,w&&_].filter(Boolean).join(` `)||void 0}),[w,p,m,h,_]);ee(()=>{if(f===`render`)C.preload();else if(f===`viewport`&&x.current){let e=new IntersectionObserver(t=>{t.forEach(t=>{t.isIntersecting&&(C.preload(),e.disconnect())})});return e.observe(x.current),()=>e.disconnect()}},[f,C]);let E=e=>{b.onClick?.(e),!(e.ctrlKey||e.metaKey||e.shiftKey||e.altKey||e.button!==0||e.defaultPrevented)&&(e.preventDefault(),t.navigate({url:S,replace:a,state:o}))},D=e=>{b.onFocus?.(e),f===`intent`&&!e.defaultPrevented&&C.preload()},O=e=>{b.onPointerEnter?.(e),f===`intent`&&!e.defaultPrevented&&C.preload()},k={...b,...T,ref:ne(b.ref,x),href:S,onClick:E,onFocus:D,onPointerEnter:O};return v&&i(y)?n(y,k):g(`a`,{...k,children:y})}function ne(...e){let t=e.filter(e=>!!e);return t.length<=1?t[0]??null:e=>{let n=[];for(let r of t){let t=Q(r,e);n.push(t??(()=>Q(r,null)))}return()=>n.forEach(e=>e())}}function Q(e,t){if(typeof e==`function`)return e(t);e&&(e.current=t)}function re(e){return()=>g(t,{fallback:g(e,{}),children:F()})}function ie(t){class n extends e{constructor(e){super(e),this.state={children:e.children,error:null}}static getDerivedStateFromError(e){return{error:[e]}}static getDerivedStateFromProps(e,t){return e.children===t.children?t:{children:e.children,error:null}}render(){return this.state.error?g(t,{error:this.state.error[0]}):this.props.children}}return()=>g(n,{children:F()})}function ae(e){return new $(_(e),e=>e,[],[],[])}var $=class e{pattern;_;constructor(e,t,n,r,i){let{keys:a,pattern:o}=h(e),s=h(e,!0).pattern,c=v(e);this.pattern=e,this._={keys:a,regex:o,looseRegex:s,weights:c,mapSearch:t,handles:n,components:r,preloaded:!1,preloaders:i}}route(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(_(`${this.pattern}/${t}`),n,r,i,a)}search(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return t=y(t),new e(this.pattern,e=>{let r=n(e);return{...r,...t(r)}},r,i,a)}handle(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(this.pattern,n,[...r,t],i,a)}preloader(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(this.pattern,n,r,i,[...a,t])}component(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(this.pattern,n,r,[...i,o(t)],a)}lazy(e){let t=a(async()=>{let t=await e();return{default:o(`default`in t?t.default:t)}});return this.preloader(e).component(t)}suspense(e){return this.component(re(e))}error(e){return this.component(ie(e))}async preload(){let{preloaded:e,preloaders:t}=this._;e||(this._.preloaded=!0,await Promise.all(t.map(e=>e())))}toString(){return this.pattern}};export{V as BrowserHistory,q as HashHistory,Z as Link,j as MatchContext,K as MemoryHistory,X as Navigate,Y as Outlet,M as OutletContext,$ as Route,G as Router,A as RouterContext,J as RouterRoot,ae as route,P as useHandles,te as useLocation,R as useMatch,L as useNavigate,F as useOutlet,z as useParams,N as useRouter,B as useSearch,I as useSubscribe};
+import{Component as e,Suspense as t,cloneElement as n,createContext as r,isValidElement as i,lazy as a,memo as o,useCallback as s,useContext as c,useEffect as ee,useLayoutEffect as l,useMemo as u,useRef as d,useState as f,useSyncExternalStore as p}from"react";import{inject as m,parse as h}from"regexparam";import{jsx as g}from"react/jsx-runtime";function _(e){return`/${e}`.replaceAll(/\/+/g,`/`).replace(/(.+)\/$/,`$1`)}function v(e){return e.split(`/`).slice(1).map(e=>e.includes(`*`)?0:e.includes(`:`)?1:2)}function y(e){return typeof e==`function`?e:t=>{let n=e[`~standard`].validate(t);if(n instanceof Promise)throw Error(`[Waymark] Validation must be synchronous`);if(n.issues)throw Error(`[Waymark] Validation failed`,{cause:n.issues});return n.value}}function b(e){return Object.entries(e).filter(([e,t])=>t!==void 0).map(([e,t])=>`${e}=${encodeURIComponent(S(t))}`).join(`&`)}function x(e){let t=new URLSearchParams(e);return Object.fromEntries([...t.entries()].map(([e,t])=>(t=decodeURIComponent(t),[e,C(t)?JSON.parse(t):t])))}function S(e){return typeof e==`string`&&!C(e)?e:JSON.stringify(e)}function C(e){try{return JSON.parse(e),!0}catch{return!1}}function w(e,t){return _(`${t}/${e}`)}function T(e,t){return(e===t||e.startsWith(`${t}/`))&&(e=e.slice(t.length)||`/`),e}function E(e,t){return[e,b(t)].filter(Boolean).join(`?`)}function D(e){let{pathname:t,search:n}=new URL(e,`http://w`);return{path:t,search:x(n)}}function O(e,t,n,r){let i=e.exec(T(n,r));if(!i)return null;let a={};return t.forEach((e,t)=>{let n=i[t+1];n&&(a[e]=n)}),a}function k(e){return[...e].sort((e,t)=>{let n=e.route._.weights,r=t.route._.weights,i=Math.max(n.length,r.length);for(let e=0;e<i;e++){let t=n[e]??-1,i=r[e]??-1;if(t!==i)return i-t}return 0})}const A=r(null),j=r(null),M=r(null);function N(){let e=c(A);if(!e)throw Error(`[Waymark] useRouter must be used within a router context`);return e}function P(){let e=c(j);return u(()=>e?.route._.handles??[],[e])}function F(){return c(M)}function I(e,t){return p(e.history.subscribe,t,t)}function L(){let e=N();return u(()=>e.navigate.bind(e),[e])}function R(){let e=N(),t=I(e,e.history.getPath),n=I(e,e.history.getSearch),r=I(e,e.history.getState);return u(()=>({path:t,search:n,state:r}),[t,n,r])}function z(e){let t=N(),n=I(t,t.history.getPath);return u(()=>t.match(n,e),[t,n,e])}function B(e){let t=z({from:e});if(!t)throw Error(`[Waymark] Can't read params for non-matching route: ${e}`);return t.params}function te(e){let t=N(),n=t.getRoute(e),r=I(t,t.history.getSearch);return[u(()=>n._.mapSearch(r),[n,r]),s((e,r)=>{let i=n._.mapSearch(t.history.getSearch());e=typeof e==`function`?e(i):e;let a=E(t.history.getPath(),{...i,...e});t.navigate({url:a,replace:r})},[t,n])]}var V=class e{static patchKey=Symbol.for(`waymark_history_patch_v01`);memo;constructor(){if(typeof history<`u`&&!(e.patchKey in window)){for(let e of[H,U]){let t=history[e];history[e]=function(...n){let r=t.apply(this,n),i=new Event(e);return i.arguments=n,dispatchEvent(i),r}}window[e.patchKey]=!0}}getSearchMemo=e=>this.memo?.search===e?this.memo.parsed:(this.memo={search:e,parsed:x(e)}).parsed;getPath=()=>location.pathname;getSearch=()=>this.getSearchMemo(location.search);getState=()=>history.state;go=e=>history.go(e);push=e=>{let{url:t,replace:n,state:r}=e;history[n?U:H](r,``,t)};subscribe=e=>(W.forEach(t=>window.addEventListener(t,e)),()=>{W.forEach(t=>window.removeEventListener(t,e))})};const H=`pushState`,U=`replaceState`,W=[`popstate`,H,U,`hashchange`];var G=class{basePath;routes;history;ssrContext;defaultLinkOptions;_;constructor(e){let{basePath:t=`/`,routes:n,history:r,ssrContext:i,defaultLinkOptions:a}=e;this.basePath=_(t),this.routes=n,this.history=r??new V,this.ssrContext=i,this.defaultLinkOptions=a,this._={routeMap:new Map(n.map(e=>[e.pattern,e]))}}getRoute(e){if(typeof e!=`string`)return e;let t=this._.routeMap.get(e);if(!t)throw Error(`[Waymark] Route not found for pattern: ${e}`);return t}match(e,t){let{from:n,strict:r,params:i}=t,a=this.getRoute(n),o=O(r?a._.regex:a._.looseRegex,a._.keys,e,this.basePath);return!o||i&&Object.keys(i).some(e=>i[e]!==o[e])?null:{route:a,params:o}}matchAll(e){return k(this.routes.map(t=>this.match(e,{from:t,strict:!0})).filter(e=>!!e))[0]??null}createUrl(e){let{to:t,params:n={},search:r={}}=e,{pattern:i}=this.getRoute(t);return E(w(m(i,n),this.basePath),r)}navigate(e){if(typeof e==`number`)this.history.go(e);else if(`url`in e)this.history.push(e);else{let{replace:t,state:n}=e;this.history.push({url:this.createUrl(e),replace:t,state:n})}}},K=class{stack=[];index=0;listeners=new Set;constructor(e=`/`){this.stack.push({...D(e),state:void 0})}getCurrent=()=>this.stack[this.index];getPath=()=>this.getCurrent().path;getSearch=()=>this.getCurrent().search;getState=()=>this.getCurrent().state;go=e=>{let t=this.index+e;this.stack[t]&&(this.index=t,this.listeners.forEach(e=>e()))};push=e=>{let{url:t,replace:n,state:r}=e,i={...D(t),state:r};this.stack=this.stack.slice(0,this.index+1),n?this.stack[this.index]=i:this.index=this.stack.push(i)-1,this.listeners.forEach(e=>e())};subscribe=e=>(this.listeners.add(e),()=>{this.listeners.delete(e)})},q=class extends V{getHashUrl=()=>new URL(location.hash.slice(1),`http://w`);getPath=()=>this.getHashUrl().pathname;getSearch=()=>this.getSearchMemo(this.getHashUrl().search);push=e=>{let{url:t,replace:n,state:r}=e;history[n?`replaceState`:`pushState`](r,``,`#${t}`)}};function J(e){let[t]=f(()=>`router`in e?e.router:new G(e)),n=I(t,t.history.getPath),r=u(()=>t.matchAll(n),[t,n]);return r||console.error(`[Waymark] No matching route found for path:`,n),u(()=>g(A.Provider,{value:t,children:g(j.Provider,{value:r,children:r?.route._.components.reduceRight((e,t)=>g(M.Provider,{value:e,children:g(t,{})}),null)})}),[t,r])}function Y(){return F()}function X(e){let t=N();return l(()=>t.navigate(e),[]),t.ssrContext&&(t.ssrContext.redirect=t.createUrl(e)),null}function Z(e){let t=N(),{to:r,replace:a,state:o,params:s,search:c,strict:l,preload:f,style:p,className:m,activeStyle:h,activeClassName:_,asChild:v,children:y,...b}={...t.defaultLinkOptions,...e},x=d(null),S=t.createUrl(e),C=u(()=>t.getRoute(e.to),[t,e.to]),w=!!z({from:C,strict:l,params:s}),T=u(()=>({"data-active":w,style:{...p,...w&&h},className:[m,w&&_].filter(Boolean).join(` `)||void 0}),[w,p,m,h,_]);ee(()=>{if(f===`render`)C.preload();else if(f===`viewport`&&x.current){let e=new IntersectionObserver(t=>{t.forEach(t=>{t.isIntersecting&&(C.preload(),e.disconnect())})});return e.observe(x.current),()=>e.disconnect()}},[f,C]);let E=e=>{b.onClick?.(e),!(e.ctrlKey||e.metaKey||e.shiftKey||e.altKey||e.button!==0||e.defaultPrevented)&&(e.preventDefault(),t.navigate({url:S,replace:a,state:o}))},D=e=>{b.onFocus?.(e),f===`intent`&&!e.defaultPrevented&&C.preload()},O=e=>{b.onPointerEnter?.(e),f===`intent`&&!e.defaultPrevented&&C.preload()},k={...b,...T,ref:ne(b.ref,x),href:S,onClick:E,onFocus:D,onPointerEnter:O};return v&&i(y)?n(y,k):g(`a`,{...k,children:y})}function ne(...e){let t=e.filter(e=>!!e);return t.length<=1?t[0]??null:e=>{let n=[];for(let r of t){let t=Q(r,e);n.push(t??(()=>Q(r,null)))}return()=>n.forEach(e=>e())}}function Q(e,t){if(typeof e==`function`)return e(t);e&&(e.current=t)}function re(e){return()=>g(t,{fallback:g(e,{}),children:F()})}function ie(t){class n extends e{constructor(e){super(e),this.state={children:e.children,error:null}}static getDerivedStateFromError(e){return{error:[e]}}static getDerivedStateFromProps(e,t){return e.children===t.children?t:{children:e.children,error:null}}render(){return this.state.error?g(t,{error:this.state.error[0]}):this.props.children}}return()=>g(n,{children:F()})}function ae(e){return new $(_(e),e=>e,[],[],[])}var $=class e{pattern;_;constructor(e,t,n,r,i){let{keys:a,pattern:o}=h(e),s=h(e,!0).pattern,c=v(e);this.pattern=e,this._={keys:a,regex:o,looseRegex:s,weights:c,mapSearch:t,handles:n,components:r,preloaded:!1,preloaders:i}}route(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(_(`${this.pattern}/${t}`),n,r,i,a)}search(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return t=y(t),new e(this.pattern,e=>{let r=n(e);return{...r,...t({...e,...r})}},r,i,a)}handle(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(this.pattern,n,[...r,t],i,a)}preloader(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(this.pattern,n,r,i,[...a,t])}component(t){let{mapSearch:n,handles:r,components:i,preloaders:a}=this._;return new e(this.pattern,n,r,[...i,o(t)],a)}lazy(e){let t=a(async()=>{let t=await e();return{default:o(`default`in t?t.default:t)}});return this.preloader(e).component(t)}suspense(e){return this.component(re(e))}error(e){return this.component(ie(e))}async preload(){let{preloaded:e,preloaders:t}=this._;e||(this._.preloaded=!0,await Promise.all(t.map(e=>e())))}toString(){return this.pattern}};export{V as BrowserHistory,q as HashHistory,Z as Link,j as MatchContext,K as MemoryHistory,X as Navigate,Y as Outlet,M as OutletContext,$ as Route,G as Router,A as RouterContext,J as RouterRoot,ae as route,P as useHandles,R as useLocation,z as useMatch,L as useNavigate,F as useOutlet,B as useParams,N as useRouter,te as useSearch,I as useSubscribe};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waymark",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "license": "MIT",
   "author": "strblr",
   "description": "Lightweight type-safe router for React",
@@ -15,9 +15,9 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/strblr/waymark"
+    "url": "git+https://github.com/strblr/waymark.git"
   },
-  "homepage": "https://github.com/strblr/waymark",
+  "homepage": "https://waymark.strblr.workers.dev",
   "bugs": "https://github.com/strblr/waymark/issues",
   "keywords": [
     "react",
@@ -40,8 +40,8 @@
   ],
   "scripts": {
     "build": "tsc --noEmit && tsdown --minify --platform browser",
-    "copy-readme": "cp ../../README.md README.md",
-    "prepublishOnly": "bun run build && bun run copy-readme"
+    "prepublishOnly": "bun run build && cp ../../README.md README.md",
+    "postpublish": "rm -f README.md"
   },
   "devDependencies": {
     "@types/bun": "^1.3.6",

package/tsdown.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from "tsdown";
-
-export default defineConfig({
-  entry: ["./src/index.ts"],
-  report: {
-    brotli: true
-  }
-});