docs: document typed URLs and navigation

Author: cpojer

docs/guide/pages-routing/overview.md

@@ -153,42 +153,48 @@ Render and prerender flags combine like this:
 | Island page + `ssr = false`            | Invalid. Island pages already use the island renderer.                    |
 | `output: "static"` + `prerender` unset | Auto-prerender pages that have known paths, including client-only shells. |
 
-Use the `Link` component for SPA navigation between pages. It renders an `<a>` tag that intercepts clicks and navigates without a full page reload:
+### Typed navigation
+
+Use the `Link` component for SPA navigation between pages. Build dynamic URLs with [`routeUrl()`](../type-safety.md#typed-urls-and-navigation) to check the route pattern and its parameters:
 
 ::: code-group
 
 ```tsx [React]
 import { Link } from "@void/react";
+import { routeUrl } from 'void/routes';
 
 <Link href="/users">Users</Link>
-<Link href={`/users/${id}`}>View</Link>
+<Link href={routeUrl('/users/:id', { params: { id } })}>View</Link>
 ```
 
 ```vue [Vue]
 <script setup lang="ts">
 import { Link } from '@void/vue';
+import { routeUrl } from 'void/routes';
 </script>
 
 <template>
   <Link href="/users">Users</Link>
-  <Link :href="`/users/${id}`">View</Link>
+  <Link :href="routeUrl('/users/:id', { params: { id } })">View</Link>
 </template>
 ```
 
 ```svelte [Svelte]
 <script>
   import { Link } from "@void/svelte";
+  import { routeUrl } from 'void/routes';
 </script>
 
 <Link href="/users">Users</Link>
-<Link href={`/users/${id}`}>View</Link>
+<Link href={routeUrl('/users/:id', { params: { id } })}>View</Link>
 ```
 
 ```tsx [Solid]
 import { Link } from "@void/solid";
+import { routeUrl } from 'void/routes';
 
 <Link href="/users">Users</Link>
-<Link href={`/users/${id}`}>View</Link>
+<Link href={routeUrl('/users/:id', { params: { id } })}>View</Link>
 ```
 
 :::
@@ -222,17 +228,28 @@ import { Link } from "@void/solid";
 
 `prefetch` and `reloadDocument` work only with GET links. GET `data` becomes query parameters; use scalar values or arrays.
 
-For programmatic navigation, use `useRouter()`:
+For programmatic navigation, use `useRouter()`. Pass a typed destination object to `visit()`, `prefetch()`, or `flush()`:
 
 ```ts
 import { useRouter } from '@void/vue'; // or "@void/react", "@void/svelte", "@void/solid"
+import type { RouteDestination } from 'void/routes';
 
 const router = useRouter();
-router.visit('/users');
+const profile = {
+  pathname: '/users/:id',
+  params: { id: 42 },
+  query: { tab: 'activity' },
+} satisfies RouteDestination;
+
+await router.prefetch(profile);
+await router.visit(profile);
+router.flush(profile); // clear its prefetched data
 router.refresh(); // re-fetch current page props, keeping the same history entry
 router.visit('/logout', { method: 'POST' }); // non-GET navigation
 ```
 
+You can also pass URL strings or `URL` instances to these router methods. See [Typed URLs and Navigation](../type-safety.md#typed-urls-and-navigation) for query values, fragments, and catch-all routes.
+
 `router.visit()` updates the page in place for same-origin URLs. `http(s)` URLs on another origin get a full page load, and other schemes such as `javascript:` are rejected.
 
 For dynamic route params, use `useParams()` from the same adapter package:

docs/guide/type-safety.md

@@ -102,13 +102,55 @@ const deleteForm = useForm('/users/:id?delete', { id: '' }, { params: { id } });
 
 The `action()` helper gets the same type checking. See [Actions & Forms](./pages-routing/actions-and-forms) for the full API.
 
+## Typed URLs and Navigation
+
+Use `routeUrl()` from `void/routes` to build URLs from your app's page, HTTP, and WebSocket route patterns. For a page at `pages/users/[id].tsx`, the pattern is `/users/:id`:
+
+```ts
+import { routeUrl } from 'void/routes';
+
+const url = routeUrl('/users/:id', {
+  params: { id: 42 },
+  query: { tab: 'activity' },
+  hash: 'details',
+});
+// /users/42?tab=activity#details
+```
+
+Your editor autocompletes route patterns and parameter names. TypeScript checks that the route exists and all required parameters are supplied. Parameter values accept strings or numbers; Void encodes them for the URL. Query keys are chosen by your app, and values can be strings, numbers, booleans, or arrays of those values. Arrays become repeated query parameters; `null` and `undefined` values are omitted.
+
+Pass the returned string to `Link`, a plain `<a>`, or `c.redirect()`. For programmatic navigation and `c.rewrite()`, you can pass a destination object directly:
+
+```ts
+import type { RouteDestination } from 'void/routes';
+
+const profile = {
+  pathname: '/users/:id',
+  params: { id: 42 },
+  query: { tab: 'activity' },
+  hash: 'details',
+} satisfies RouteDestination;
+```
+
+Destination objects use the same parameter checking and URL encoding as `routeUrl()`. See [Pages Routing](./pages-routing/overview.md#typed-navigation) for links and router methods, and [Rewrites](../reference/api/rewrites.md#c-rewrite-destination) for server navigation.
+
+For a catch-all page such as `pages/files/[...path].tsx`, use `/files/:path{.+}` and pass the full path as one value:
+
+```ts
+routeUrl('/files/:path{.+}', { params: { path: 'docs/get started' } });
+// /files/docs/get%20started
+```
+
+Route types update with the dev server. For CI or standalone typechecking, run `void prepare` and follow [Setup](#setup). The [API reference](../reference/api/types.md#void-routes) lists the URL helper and route types.
+
 ## What Gets Checked
 
 | Layer        | What's type-checked                                                                                                   |
 | ------------ | --------------------------------------------------------------------------------------------------------------------- |
 | Database     | Table columns, value types, insert/update shapes from Drizzle schema                                                  |
 | Handlers     | `c.env` bindings, validator input, return type                                                                        |
 | Fetch client | Route paths, HTTP methods, `body`/`query`/`params`, response type                                                     |
+| Navigation   | Route patterns and required parameter names and values in `routeUrl()` and destination objects                        |
 | `useForm`    | Action URLs, `data` fields, `errors` keys, `reset()` args (including `{ initial: true }`), `params`, `resetOnSuccess` |
 | `action()`   | Action URLs, `data` payload, `params`                                                                                 |
 

docs/reference/api.md

@@ -26,7 +26,7 @@ Use this reference to find public imports, signatures, and return types. For set
 | [Database and seeding](./api/database.md)          | Queries, operators, and seed scripts.                           |
 | [KV, storage, AI, and logging](./api/resources.md) | Resource clients, cache revalidation, and logs.                 |
 | [Deployment artifacts](./api/deploy.md)            | Package built apps for managed deployment.                      |
-| [Types](./api/types.md)                            | Handler context, route types, and head metadata.                |
+| [Types](./api/types.md)                            | Typed URLs, route types, handler context, and head metadata.    |
 | [Environment variables](./api/env.md)              | Validated environment values and binding types.                 |
 | [Pages adapters](./api/pages.md)                   | React, Vue, Svelte, Solid, and Markdown.                        |
 
@@ -64,7 +64,7 @@ Import Void's app-facing APIs from these paths:
 | `void/limits`             | `UsageLimit`, `UsageLimitData`, and `readUsageLimit`. AI and Sandbox limits reject with `UsageLimit`; uncaught limits in Void routes and Pages actions return structured HTTP 429 responses.                                                                                                                                                                                                                                                                                   |
 | `void/isr`                | `revalidate(options)` for on-demand ISR cache invalidation                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `void/log`                | `logger` structured logging helper                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `void/routes`             | `RouteMap` and `WebSocketRouteMap` stubs (types only)                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `void/routes`             | [`routeUrl()`](./api/types.md#routeurl-path-options), `RouteDestination`, `RoutePath`, `RouteOptions`, `RouteUrlInput`, and generated route maps                                                                                                                                                                                                                                                                                                                               |
 | `void/queues`             | `queues` proxy for sending messages to typed queues                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `void/email`              | `sendEmail`, `createEmail`, `defineEmail`, `parseEmail`, `replyEmail`, `MimeError`, `ParseEmailError`, and address, attachment, result, and handler types. See [Email](../guide/email.md).                                                                                                                                                                                                                                                                                     |
 | `void/email/testing`      | `createEmailTestHarness` and `createInboundTestHarness` to capture sends and deliver test messages to `email/` handlers.                                                                                                                                                                                                                                                                                                                                                       |

docs/reference/api/pages.md

@@ -6,6 +6,14 @@ outline: deep
 
 Framework adaptors for [Pages Routing](../../guide/pages-routing/overview). Each adaptor provides a Vite plugin and client-side runtime.
 
+## Navigation destinations {#navigation-destinations}
+
+All four adapters support typed URLs through [`routeUrl()`](./types.md#routeurl-path-options). Pass the returned string to `Link`'s `href`.
+
+The router's `visit(destination, options?)`, `prefetch(destination, options?)`, and `flush(destination, method?)` accept [`RouteUrlInput`](./types.md#route-types): a string, `URL`, or typed destination object.
+
+See [Typed navigation](../../guide/pages-routing/overview.md#typed-navigation) for framework examples.
+
 ## `@void/vue` {#void-vue}
 
 ### `voidVue(options?)` {#voidvue-options}

docs/reference/api/rewrites.md

@@ -10,6 +10,24 @@ URL rewrites re-dispatch a request at a different internal path without changing
 
 Re-dispatches the current request at `destination` and returns the resulting `Response`. The browser URL does not change — this is a server-side hop. If `destination` has no query string, the original request query is preserved. If `destination` includes a query string, it replaces the original query. `destination` must start with `/`; known generated routes autocomplete via [`RewriteDestination`](#rewritedestination), while arbitrary strings remain accepted for dynamic paths.
 
+Pass a [`RouteDestination`](./types.md#route-types) object to check the route pattern and its parameters:
+
+```ts
+return c.rewrite({
+  pathname: '/users/:id',
+  params: { id: 42 },
+  query: { tab: 'activity' },
+});
+```
+
+For a typed redirect, build the URL with [`routeUrl()`](./types.md#routeurl-path-options):
+
+```ts
+import { routeUrl } from 'void/routes';
+
+return c.redirect(routeUrl('/users/:id', { params: { id: 42 } }));
+```
+
 `c.redirect()` merges request query parameters into internal destinations, with destination values taking precedence. Redirecting a [named action](../../guide/pages-routing/actions-and-forms.md#named-actions) to a GET page drops the action key: `POST /users/42?delete&tab=profile` redirects to `/users/42?tab=profile`. Redirects that preserve the request method keep the action key: `307` and `308`, or `301` and `302` after a `PUT`, `PATCH`, or `DELETE`.
 
 ```ts
@@ -25,7 +43,7 @@ export const GET = defineHandler((c) => {
 
 ```ts
 interface CloudContext {
-  rewrite(destination: RewriteDestination): Promise<Response>;
+  rewrite(destination: RewriteDestination | RouteDestination): Promise<Response>;
 }
 ```
 

docs/reference/api/types.md

@@ -91,3 +91,44 @@ Generated route types used by the typed `fetch` client. Contains each route’s
 ```ts
 import type { RouteMap } from 'void/routes';
 ```
+
+## `void/routes` {#void-routes}
+
+### `routeUrl(path, options?)` {#routeurl-path-options}
+
+Build a relative URL string from a known page, HTTP, or WebSocket route pattern:
+
+```ts
+import { routeUrl } from 'void/routes';
+
+routeUrl('/users/:id', {
+  params: { id: 42 },
+  query: { tab: 'activity' },
+  hash: 'details',
+});
+// /users/42?tab=activity#details
+```
+
+| Option   | Type           | Description                                                                        |
+| -------- | -------------- | ---------------------------------------------------------------------------------- |
+| `params` | Route-specific | Required for dynamic routes. Each parameter accepts a `string` or `number`.        |
+| `query`  | `RouteQuery`   | Query parameters. Arrays become repeated keys; `null` and `undefined` are omitted. |
+| `hash`   | `string`       | URL fragment, such as `'details'` or `'#details'`.                                 |
+
+Static routes accept optional `query` and `hash` options. Pass raw parameter values for URL encoding. Catch-all parameters preserve `/` separators between segments. Invalid or missing path parameters throw a `TypeError`.
+
+Use the returned string with `Link`, `<a>`, and `c.redirect()`. See [Typed URLs and Navigation](../../guide/type-safety.md#typed-urls-and-navigation) for setup and examples.
+
+### Route types {#route-types}
+
+Import these types from `void/routes`:
+
+| Type                  | Description                                                                                     |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| `RoutePathMap`        | Generated map of page, HTTP, and WebSocket route patterns to their parameter names.             |
+| `RoutePath`           | Union of the known route patterns in `RoutePathMap`.                                            |
+| `RouteOptions<P>`     | Options for a route pattern `P`, including its required `params`, optional `query`, and `hash`. |
+| `RouteDestination<P>` | `{ pathname: P }` with `RouteOptions<P>`. Defaults to all known routes when `P` is omitted.     |
+| `RouteUrlInput`       | `string`, `URL`, or `RouteDestination`; accepted by router navigation methods.                  |
+| `RouteQuery`          | Query keys mapped to `RouteQueryValue` or readonly arrays of those values.                      |
+| `RouteQueryValue`     | `string`, `number`, `boolean`, `null`, or `undefined`.                                          |