void 1.5.0 → 1.6.0

package/docs/reference/api/pages.md

@@ -8,12 +8,42 @@ Framework adaptors for [Pages Routing](../../guide/pages-routing/overview). Each
 
 ## 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`.
+All four adapters support typed URLs through [`routeUrl()`](./types.md#routeurl-path-options). Pass the returned string to `Link`'s `href`, which has the type [`Href`](./types.md#route-types).
 
 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.
 
+With [`routing.typedRoutes`](../config.md#routing-typedroutes), `href` and router strings must match one of your routes, or be a same-page or external URL. Without it, both accept any string.
+
 See [Typed navigation](../../guide/pages-routing/overview.md#typed-navigation) for framework examples.
 
+## Prefetching {#prefetching}
+
+`Link`'s `prefetch` prop takes `true`, `false`, a strategy, or an array of strategies:
+
+```ts
+type LinkPrefetchStrategy = 'hover' | 'click' | 'mount' | 'visible';
+```
+
+| Value               | Loads the page                                                                                |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `'hover'` or `true` | When the pointer rests on the link for `hoverDelay`, when it gets keyboard focus, or on touch |
+| `'click'`           | When the mouse button or finger goes down, just before the click                              |
+| `'mount'`           | As soon as the link renders                                                                   |
+| `'visible'`         | Once the link has stayed in view for 300 ms. Links scrolled quickly past are skipped          |
+| `false`             | Never                                                                                         |
+
+With an array such as `['visible', 'hover']`, the first strategy to happen loads the page, and later ones reuse it. `prefetch` works only on GET links, and links to other sites are never prefetched. No strategy prefetches while the browser reports data saver or a 2G connection, which only Chromium-based browsers report; calling `router.prefetch()` yourself still loads the page.
+
+`cacheFor` sets how long a prefetched page is reused, in milliseconds or as a duration such as `'5m'`. A pair such as `['30s', '5m']` treats the page as fresh for 30 seconds, then still shows it for up to 5 minutes while loading a fresh copy in the background.
+
+Each adapter plugin's `prefetch` option sets app-wide values:
+
+| Option            | Default | Description                                                                                                                                                                                                 |
+| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultStrategy` | `false` | The `prefetch` value for every `Link` that doesn't set its own. A `Link`'s own `prefetch` replaces it, and `prefetch={false}` turns it off. Links with a non-GET `method` or `reloadDocument` don't use it. |
+| `hoverDelay`      | `75`    | Milliseconds the pointer rests on a link before `'hover'` prefetches.                                                                                                                                       |
+| `cacheFor`        | `'30s'` | The `cacheFor` value for every `Link` that doesn't set its own.                                                                                                                                             |
+
 ## `@void/vue` {#void-vue}
 
 ### `voidVue(options?)` {#voidvue-options}
@@ -41,8 +71,9 @@ interface VoidVueOptions {
   vue?: VuePluginOptions; // passed through to @vitejs/plugin-vue
   viewTransitions?: boolean; // enable View Transitions API for navigations
   prefetch?: {
-    hoverDelay?: number;
-    cacheFor?: number | string | [string, string];
+    defaultStrategy?: boolean | LinkPrefetchStrategy | LinkPrefetchStrategy[]; // default: false
+    hoverDelay?: number; // default: 75 (ms)
+    cacheFor?: number | string | [string, string]; // default: '30s'
   };
 }
 ```
@@ -51,16 +82,16 @@ interface VoidVueOptions {
 
 Imported from `"@void/vue"`.
 
-| Export                             | Description                                                                                                                                                                                                                                       |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Link`                             | Vue component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `onNavigate`. |
-| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`.                                                                        |
-| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                               |
-| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                             |
-| `useForm(url, defaults, options?)` | Typed reactive form helper bound to a page action URL. Returns `{ data, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                             |
-| `useIslandForm(defaults)`          | Form helper for island components. Same form state as `useForm()`, plus `submit(url, method)`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                            |
-| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                         |
-| `useShared()`                      | Returns shared data injected by middleware via `c.set("shared", {...})`.                                                                                                                                                                          |
+| Export                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Link`                             | Vue component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `activeMatch`, `onNavigate`. Adds `aria-current="page"` and `data-void-active` to the link to the current page ([active links](../../guide/pages-routing/overview.md#active-links)), and `data-void-pending` to links to a page while it loads ([pending links](../../guide/pages-routing/overview.md#pending-links)). |
+| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                                                                                                                                                                                                                                                                                                                                      |
+| `useForm(url, defaults, options?)` | Typed reactive form helper bound to a page action URL. Returns `{ data, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                                                                                                                                                                                                                                                                                                                      |
+| `useIslandForm(defaults)`          | Form helper for island components. Same form state as `useForm()`, plus `submit(url, method)`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                                                                                                                                                                                                                                                                                                                                     |
+| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params, preserveScroll }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                                                                                                                                                                                                                                                                                                                  |
+| `useShared()`                      | Returns shared data. Middleware sets it with `c.set("shared", {...})`; a loader or action can update it. See [Shared data](../../guide/pages-routing/layouts.md#shared-data).                                                                                                                                                                                                                                                                                                                                                                              |
 
 Vue `Link` GET `data` is merged into the rendered `href` query string. Primitive values are serialized with `String(value)`, arrays become repeated keys, `null` and `undefined` are omitted, and nested objects throw. `prefetch` and `reloadDocument` are GET-only and throw for mutation links.
 
@@ -93,8 +124,9 @@ interface VoidReactOptions {
   react?: ReactPluginOptions; // passed through to @vitejs/plugin-react
   viewTransitions?: boolean; // enable View Transitions API for navigations
   prefetch?: {
-    hoverDelay?: number;
-    cacheFor?: number | string | [string, string];
+    defaultStrategy?: boolean | LinkPrefetchStrategy | LinkPrefetchStrategy[]; // default: false
+    hoverDelay?: number; // default: 75 (ms)
+    cacheFor?: number | string | [string, string]; // default: '30s'
   };
 }
 ```
@@ -103,17 +135,17 @@ interface VoidReactOptions {
 
 Imported from `"@void/react"`.
 
-| Export                             | Description                                                                                                                                                                                                                                         |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Link`                             | React component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `onNavigate`. |
-| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`. React navigations are scheduled as transitions.                          |
-| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                 |
-| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                               |
-| `useForm(url, defaults, options?)` | Form helper hook. Returns `{ data, setData, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                                           |
-| `useIslandForm(defaults)`          | Form helper hook for island components. Same form state as `useForm()`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                                                     |
-| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                           |
-| `useShared()`                      | Returns shared data injected by middleware via `c.set("shared", {...})`.                                                                                                                                                                            |
-| `Deferred<T>`                      | React-only prop type for `defer()` results. It is `Promise<T>` and is consumed with React `use()`.                                                                                                                                                  |
+| Export                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Link`                             | React component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `activeMatch`, `onNavigate`. Adds `aria-current="page"` and `data-void-active` to the link to the current page ([active links](../../guide/pages-routing/overview.md#active-links)), and `data-void-pending` to links to a page while it loads ([pending links](../../guide/pages-routing/overview.md#pending-links)). |
+| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`. React navigations are scheduled as transitions.                                                                                                                                                                                                                                                                                                                                   |
+| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                                                                                                                                                                                                                                                                                                                                        |
+| `useForm(url, defaults, options?)` | Form helper hook. Returns `{ data, setData, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                                                                                                                                                                                                                                                                                                                                                    |
+| `useIslandForm(defaults)`          | Form helper hook for island components. Same form state as `useForm()`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                                                                                                                                                                                                                                                                                                                                                              |
+| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params, preserveScroll }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                                                                                                                                                                                                                                                                                                                    |
+| `useShared()`                      | Returns shared data. Middleware sets it with `c.set("shared", {...})`; a loader or action can update it. See [Shared data](../../guide/pages-routing/layouts.md#shared-data).                                                                                                                                                                                                                                                                                                                                                                                |
+| `Deferred<T>`                      | React-only prop type for `defer()` results. It is `Promise<T>` and is consumed with React `use()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 React `Link` GET `data` is merged into the rendered `href` query string. Primitive values are serialized with `String(value)`, arrays become repeated keys, `null` and `undefined` are omitted, and nested objects throw. `prefetch` and `reloadDocument` are GET-only and throw for mutation links.
 
@@ -128,6 +160,23 @@ When explicitly annotating props, import `Deferred` from the framework adapter
 package (`@void/react`, `@void/vue`, `@void/svelte`, or `@void/solid`) so the
 type matches that adapter's client runtime shape.
 
+### React navigation completion {#react-navigation-completion}
+
+By default, `await router.visit()` and `await router.refresh()` wait for React to commit the updated page and URL. You can also request this explicitly with `{ resolveOn: 'commit' }`.
+
+When awaiting navigation inside `startTransition`, a `<form action>`, `useActionState`, or an async `useForm()` callback, pass `{ resolveOn: 'data' }`:
+
+```tsx
+startTransition(async () => {
+  await saveUser();
+  await router.refresh({ resolveOn: 'data' });
+});
+
+await router.visit('/account', { resolveOn: 'data' });
+```
+
+With `'data'`, the promise resolves when the destination's page data is ready, allowing the Action to finish while React renders the update. The transition can remain pending through Suspense. The DOM and URL may still show the previous page after `await`; use an effect or ref callback for work that requires the updated DOM.
+
 ## `@void/svelte` {#void-svelte}
 
 ### `voidSvelte(options?)` {#voidsvelte-options}
@@ -155,8 +204,9 @@ interface VoidSvelteOptions {
   svelte?: SveltePluginOptions; // passed through to @sveltejs/vite-plugin-svelte
   viewTransitions?: boolean; // enable View Transitions API
   prefetch?: {
-    hoverDelay?: number;
-    cacheFor?: number | string | [string, string];
+    defaultStrategy?: boolean | LinkPrefetchStrategy | LinkPrefetchStrategy[]; // default: false
+    hoverDelay?: number; // default: 75 (ms)
+    cacheFor?: number | string | [string, string]; // default: '30s'
   };
 }
 ```
@@ -165,16 +215,16 @@ interface VoidSvelteOptions {
 
 Imported from `"@void/svelte"`.
 
-| Export                             | Description                                                                                                                                                                                                                                          |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Link`                             | Svelte component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `onNavigate`. |
-| `useForm(url, defaults, options?)` | Form helper using Svelte 5 runes. Returns `{ data, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                                     |
-| `useIslandForm(defaults)`          | Form helper for island components. Same form state as `useForm()`, plus `submit(url, method)`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                               |
-| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                            |
-| `useShared()`                      | Returns shared data injected by middleware via `c.set("shared", {...})`.                                                                                                                                                                             |
-| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`.                                                                           |
-| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                  |
-| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                                |
+| Export                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Link`                             | Svelte component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `activeMatch`, `onNavigate`. Adds `aria-current="page"` and `data-void-active` to the link to the current page ([active links](../../guide/pages-routing/overview.md#active-links)), and `data-void-pending` to links to a page while it loads ([pending links](../../guide/pages-routing/overview.md#pending-links)). |
+| `useForm(url, defaults, options?)` | Form helper using Svelte 5 runes. Returns `{ data, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                                                                                                                                                                                                                                                                                                                                              |
+| `useIslandForm(defaults)`          | Form helper for island components. Same form state as `useForm()`, plus `submit(url, method)`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                                                                                                                                                                                                                                                                                                                                        |
+| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params, preserveScroll }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                                                                                                                                                                                                                                                                                                                     |
+| `useShared()`                      | Returns shared data. Middleware sets it with `c.set("shared", {...})`; a loader or action can update it. See [Shared data](../../guide/pages-routing/layouts.md#shared-data).                                                                                                                                                                                                                                                                                                                                                                                 |
+| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`.                                                                                                                                                                                                                                                                                                                                                                                    |
+| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                                                                                                                                                                                                                                                                                                                                         |
 
 Svelte `Link` GET `data` is merged into the rendered `href` query string. Primitive values are serialized with `String(value)`, arrays become repeated keys, `null` and `undefined` are omitted, and nested objects throw. `prefetch` and `reloadDocument` are GET-only and throw for mutation links.
 
@@ -205,8 +255,9 @@ interface VoidSolidOptions {
   solid?: SolidPluginOptions; // passed through to vite-plugin-solid
   viewTransitions?: boolean; // enable View Transitions API
   prefetch?: {
-    hoverDelay?: number;
-    cacheFor?: number | string | [string, string];
+    defaultStrategy?: boolean | LinkPrefetchStrategy | LinkPrefetchStrategy[]; // default: false
+    hoverDelay?: number; // default: 75 (ms)
+    cacheFor?: number | string | [string, string]; // default: '30s'
   };
 }
 ```
@@ -215,16 +266,16 @@ interface VoidSolidOptions {
 
 Imported from `"@void/solid"`.
 
-| Export                             | Description                                                                                                                                                                                                                                         |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Link`                             | Solid component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `onNavigate`. |
-| `useForm(url, defaults, options?)` | Form helper using Solid stores. Returns `{ data, setData, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                             |
-| `useIslandForm(defaults)`          | Form helper for island components. Same form state as `useForm()`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                                                          |
-| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                           |
-| `useShared()`                      | Returns shared data injected by middleware via `c.set("shared", {...})`.                                                                                                                                                                            |
-| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`.                                                                          |
-| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                 |
-| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                               |
+| Export                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Link`                             | Solid component for SPA navigation. Renders `<a>` for GET, `<button>` for non-GET methods. Props: `href`, `method`, `data`, `prefetch`, `cacheFor`, `preserveScroll`, `preserveState`, `replace`, `reloadDocument`, `viewTransition`, `activeMatch`, `onNavigate`. Adds `aria-current="page"` and `data-void-active` to the link to the current page ([active links](../../guide/pages-routing/overview.md#active-links)), and `data-void-pending` to links to a page while it loads ([pending links](../../guide/pages-routing/overview.md#pending-links)). |
+| `useForm(url, defaults, options?)` | Form helper using Solid stores. Returns `{ data, setData, post, put, patch, delete, pending, errors, error, hasChanges, wasSuccessful, recentlySuccessful, reset, setError, clearErrors, clearError }`.                                                                                                                                                                                                                                                                                                                                                      |
+| `useIslandForm(defaults)`          | Form helper for island components. Same form state as `useForm()`. `post(url)`, `put(url)`, `patch(url)`, and `delete(url)` take the action URL and submit with `fetch()`.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `action(url, options?)`            | Awaitable one-shot page action helper. Uses `POST` by default and accepts `{ data, method, params, preserveScroll }`, where `method` can be `"PUT"`, `"PATCH"`, or `"DELETE"`. Returns an `ActionResult`.                                                                                                                                                                                                                                                                                                                                                    |
+| `useShared()`                      | Returns shared data. Middleware sets it with `c.set("shared", {...})`; a loader or action can update it. See [Shared data](../../guide/pages-routing/layouts.md#shared-data).                                                                                                                                                                                                                                                                                                                                                                                |
+| `useRouter()`                      | Returns the Void Router with current route state (`url`, `path`, `query`, `params`) and navigation methods: `visit`, `refresh`, awaitable `prefetch`, `flush`, `flushAll`.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `useParams()`                      | Returns dynamic route params for the page currently being rendered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `useNavigation()`                  | Returns pending navigation state: `{ state, location, method }`, where `state` is `"idle"`, `"loading"`, or `"submitting"` and `location` is the pending destination.                                                                                                                                                                                                                                                                                                                                                                                        |
 
 Solid `Link` GET `data` is merged into the rendered `href` query string. Primitive values are serialized with `String(value)`, arrays become repeated keys, `null` and `undefined` are omitted, and nested objects throw. `prefetch` and `reloadDocument` are GET-only and throw for mutation links.
 

package/docs/reference/api/rewrites.md

@@ -20,6 +20,8 @@ return c.rewrite({
 });
 ```
 
+With [`routing.typedRoutes`](../config.md#routing-typedroutes), a string destination must be a [`RouteUrl`](./types.md#route-types): a URL that matches one of your routes. Cast a path built at runtime, such as ``c.rewrite(`/${locale}${path}` as RouteUrl)``.
+
 For a typed redirect, build the URL with [`routeUrl()`](./types.md#routeurl-path-options):
 
 ```ts
@@ -43,6 +45,7 @@ export const GET = defineHandler((c) => {
 
 ```ts
 interface CloudContext {
+  // RouteUrl instead of RewriteDestination with routing.typedRoutes
   rewrite(destination: RewriteDestination | RouteDestination): Promise<Response>;
 }
 ```
@@ -88,7 +91,7 @@ import type { RewriteDestination } from 'void/routes';
 
 Suggests known route patterns in your editor while also accepting dynamic strings. Used as:
 
-- The parameter type of [`c.rewrite()`](#c-rewrite-destination).
+- The parameter type of [`c.rewrite()`](#c-rewrite-destination), unless `routing.typedRoutes` is on.
 - The type of `destination` entries in `routing.rewrites` and `routing.fallbacks` in [`void.config.ts`](../config.md#routing).
 
 Like [`RouteMap`](./types.md#routemap), `RewriteDestination` lives in the virtual `void/routes` module and is refreshed whenever routes change.

package/docs/reference/api/types.md

@@ -117,18 +117,22 @@ routeUrl('/users/:id', {
 
 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.
+Use the returned [`RouteUrl`](#route-types) 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`.                                          |
+| 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.       |
+| `RouteUrl`            | The URL of one of your routes, returned by `routeUrl()`. `string` unless `typedRoutes` is on.     |
+| `Href`                | A `RouteUrl`, a same-page query or hash, or an external URL. `string` unless `typedRoutes` is on. |
+| `RouteUrlInput`       | `Href`, `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`.                                            |
+
+`typedRoutes` is [`routing.typedRoutes`](../config.md#routing-typedroutes). See [Checked URL strings](../../guide/type-safety.md#checked-url-strings).

package/docs/reference/api.md

@@ -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`             | [`routeUrl()`](./api/types.md#routeurl-path-options), `RouteDestination`, `RoutePath`, `RouteOptions`, `RouteUrlInput`, and generated route maps                                                                                                                                                                                                                                                                                                                               |
+| `void/routes`             | [`routeUrl()`](./api/types.md#routeurl-path-options), `RouteDestination`, `RoutePath`, `RouteOptions`, `RouteUrl`, `Href`, `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.                                                                                                                                                                                                                                                                                                                                                       |

package/docs/reference/cli/platform-installation.md

@@ -25,6 +25,7 @@ void platform install [options] [--yes]
 | `--dedicated-zone`                        | Add zone-wide catch-all routes; valid only when the app domain is the whole zone     |
 | `--no-dedicated-zone`                     | Skip zone-wide application catch-all routes                                          |
 | `--custom-domains`                        | Let projects add their own domains; needs a dedicated zone                           |
+| `--runtime-logs <full\|minimal>`          | `minimal` keeps request URLs and log and exception messages out of runtime logs      |
 | `--control-plane-domain <domain>`         | Optional API custom hostname; defaults to `workers.dev`                              |
 | `--no-control-plane-domain`               | Use the default `workers.dev` API hostname                                           |
 | `--dashboard-url <origin>`                | HTTPS origin of an optional dashboard deployed separately                            |
@@ -101,7 +102,7 @@ Use these commands to recover, update, pause, or remove an installation:
 
 ```sh
 void platform discover [--account <id>] [--installation <id-or-name>]
-void platform upgrade [id] [--runtime <path>] [--dashboard-url <origin>] [--custom-domains] [--plan] [--yes]
+void platform upgrade [id] [--runtime <path>] [--dashboard-url <origin>] [--custom-domains] [--runtime-logs <full|minimal>] [--plan] [--yes]
 void platform rollback [id] --runtime <earlier-path> [--from-runtime <current-path>] [--plan] [--yes]
 void platform repair [id] [--runtime <path>] [--dashboard-url <origin>] [--custom-domains] [--auth-config <path>] [--plan] [--yes]
 void platform disable [id] [--plan] [--yes]
@@ -113,6 +114,8 @@ void platform uninstall [id] [--plan] [--purge-data | --purge-resources] [--yes]
 
 Use the installation slug shown beside its name in `void platform list`. Installation IDs and saved connection IDs also work. Lifecycle commands require local installation records; use `discover` to restore them on another machine. Omit `id` when only one installation is configured, or choose from the interactive picker. Non-interactive commands need a slug or ID when several installations exist. Commands that make changes also require `--yes`; `--plan` only previews changes.
 
+`upgrade --runtime-logs <full|minimal>` changes what runtime logs record; without it, upgrades keep the current setting. See [Choose what runtime logs record](../../guide/platform/installation/setup.md#runtime-logs).
+
 To add or explicitly change a separately deployed dashboard after installation,
 use `repair --dashboard-url <origin>` or `upgrade --dashboard-url <origin>`.
 Preview with `--plan` first. Existing Access protection must cover the configured

package/docs/reference/cli/setup.md

@@ -32,7 +32,7 @@ void init [--tsconfig] [--github] [--git | --no-git]
           [--toolchain <name>] [--framework <name>] [--starter <name>] [--deploy <target>]
 ```
 
-Set up a new or existing Void project. In an empty directory, choose Vite+ or Vite, a framework, and a D1, PostgreSQL, MySQL, or Static Pages starter.
+Set up a new or existing Void project. In an empty directory, choose Vite+ or Vite, a framework, and a D1, PostgreSQL, MySQL, or Static Pages starter. The new app's `void.config.ts` turns on [`routing.typedRoutes`](../config.md#routing-typedroutes).
 
 Pass your choices as flags to scaffold from a script or coding agent:
 

package/docs/reference/config.md

@@ -376,6 +376,16 @@ routing: {
 }
 ```
 
+#### `routing.typedRoutes`
+
+Type-check URL strings against your app's routes in `Link`'s `href`, `router.visit()`, `router.prefetch()`, `router.flush()`, and `c.rewrite()`. Omitted or `false` means off; `void init` turns it on for new apps. It changes types only, not navigation at runtime. Strings may also be same-page queries or hashes, or `http://`, `https://`, `mailto:`, and `tel:` URLs. See [Checked URL strings](../guide/type-safety#checked-url-strings).
+
+```ts
+routing: {
+  typedRoutes: true,
+}
+```
+
 #### `routing.headers`
 
 Custom response headers. Keys are URL patterns, values are arrays of `"Name: value"` strings. See [Custom Headers](../guide/edge/headers) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Full-stack framework and deployment CLI for Cloudflare Workers, powered by Vite.",
   "homepage": "https://void.cloud",
   "bugs": {
@@ -352,11 +352,11 @@
     "@cloudflare/workers-types": "^5.20261102.1",
     "@cloudflare/workers-utils": "^0.50.2",
     "@napi-rs/keyring": "^2.1.2",
-    "@void/deploy-cloudflare": "1.5.0",
-    "@void/deploy-core": "1.5.0",
-    "@void/edge": "1.5.0",
-    "@void/isr": "1.5.0",
-    "@void/platform": "1.5.0",
+    "@void/deploy-cloudflare": "1.6.0",
+    "@void/deploy-core": "1.6.0",
+    "@void/edge": "1.6.0",
+    "@void/isr": "1.6.0",
+    "@void/platform": "1.6.0",
     "better-auth": "^1.7.14",
     "better-sqlite3": "^13.0.3",
     "blake3-jit": "^1.1.0",
@@ -367,6 +367,7 @@
     "drizzle-valibot": "^0.4.2",
     "drizzle-zod": "^0.8.3",
     "email-validator": "^2.0.4",
+    "gray-matter": "^4.0.3",
     "hono": "^4.13.16",
     "ignore": "^7.0.14",
     "jiti": "^2.7.0",
@@ -406,7 +407,7 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@void/md": "1.5.0",
+    "@void/md": "1.6.0",
     "arktype": ">=2.0.0",
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",

package/schema.json

@@ -152,6 +152,10 @@
           "type": "boolean",
           "description": "Enable inferred ISR caching. Set false to disable ISR and edge prerendering, including per-page prerender and revalidate policies. Does not disable output: static build-time prerendering."
         },
+        "typedRoutes": {
+          "type": "boolean",
+          "description": "Type-check URL strings in Link href, router navigation, and c.rewrite() against the app's routes. Omitted or false means off."
+        },
         "notFound": {
           "type": "string",
           "enum": ["single-page-application", "404-page", "none"],

package/skills/void/SKILL.md

@@ -84,6 +84,11 @@ the app's existing saved destination, including when the target project is new.
   guides and use `void info` to preserve resource names and instance keys.
 - Declare application environment keys in `env.ts` and access them through
   `void/env`; follow `docs/guide/env-vars.md` for local and production values.
+- In Pages navigation, style the current link with `Link`'s `aria-current` and `data-void-active`
+  attributes (`activeMatch="prefix"` for sections) instead of comparing `useRouter().path`; see
+  `docs/guide/pages-routing/overview.md#active-links`. Show a loading state on
+  the clicked link with `data-void-pending` instead of matching `useNavigation().location`
+  yourself; see `docs/guide/pages-routing/overview.md#pending-links`.
 - For platform setup, follow the pages linked from
   `docs/guide/self-hosted-platform.md`. Use `void platform list` to find the
   installation slug for maintenance. For recovery, use its documented resume

package/dist/client-DVtAKeUm.mjs

@@ -1 +0,0 @@
-export { r as PlatformClient } from "./client-Qayy9xEh.mjs";

package/dist/deploy-CfU7CR-b.mjs

@@ -1,2 +0,0 @@
-import "./deploy-transport-L6zzPE9T.mjs";
-export { i as checkWranglerMigrationApplySet, t as parseRootWranglerConfig, r as runDeploy } from "./deploy-CwmCcTlq.mjs";

package/dist/gen-i61rdQgg.mjs

@@ -1 +0,0 @@
-export { r as runGenCommand } from "./gen-BvVmpZ5f.mjs";