void 1.4.0 → 1.6.0

package/docs/guide/pages-routing/actions-and-forms.md

@@ -11,8 +11,8 @@ Use an action to change server data from a form or button. Define it in the page
 Export `action` from a `.server.ts` file. Use `withValidator()` with a [schema-derived validator](../database.md#schema-derived-validators) to validate the request body:
 
 ```ts
-import { users, insertUserSchema } from '@schema';
 // pages/users/index.server.ts
+import { users, insertUserSchema } from '@schema';
 import { defineHandler } from 'void';
 import { db } from 'void/db';
 
@@ -29,6 +29,8 @@ export const action = defineHandler.withValidator({
 | Nothing (void)        | Re-runs the loader, page re-renders with fresh props. |
 | `c.redirect('/path')` | Navigates to another page.                            |
 
+Middleware does not run again after the action. To change [shared data](./layouts.md#shared-data), update it in the action or redirect.
+
 ## Form
 
 Pair `Form` with `useForm` to submit values and display validation and action errors. Inputs stay editable when a submission fails.
@@ -163,7 +165,7 @@ The types are inferred from your action's `withValidator()` schema in the compan
 | `clearErrors(...fields)`         | Clear validation errors. Field names autocomplete.                                                                                                                                  |
 | `clearError()`                   | Clear `error`.                                                                                                                                                                      |
 
-Use `setError()` to display errors from your own client-side validation. Setting an error preserves errors on other fields. Changing a field clears that field's validation error automatically (`setData` in React and Solid, or assigning to `data` in Vue and Svelte).
+Use `setError()` for client-side validation. Editing a field clears its error automatically.
 
 For a native React form, use `form.post`, `form.put`, `form.patch`, or `form.delete` as a native form action. For an awaitable mutation, use `action()`. In Vue, Svelte, and Solid, form submissions return `Promise<void>`; catch thrown errors or use your framework's error handling.
 
@@ -175,7 +177,7 @@ const form = useForm('/users/:id', { name: '' }, { params: { id: '42' } });
 <Form form={form} method="put">{/* submits to /users/42 */}</Form>
 ```
 
-Create forms often need empty fields again after a successful save. Either pass `resetOnSuccess: true` in the third argument, or call `form.reset({ initial: true })` when `form.wasSuccessful` becomes `true`.
+To clear a create form after saving, pass `resetOnSuccess: true` in the third argument. Use `form.reset({ initial: true })` to restore the original values manually.
 
 ### React submission callbacks
 
@@ -188,26 +190,41 @@ const form = useForm(
   {
     onSuccess: () => setDialogOpen(false),
     onError: (error) => {
-      // A field-error map or VoidActionError for a handled action failure.
       console.error(error);
     },
   },
 );
 ```
 
-Each submission uses the callbacks from when it was dispatched. Callbacks run inside the React Action, before the updated UI commits. Use an effect or ref callback to focus an element that appears after submission.
+`onError` receives a field-error map or a `VoidActionError`. Callbacks can be async; `form.pending` stays true until they finish, and thrown errors reach the nearest React error boundary. Callbacks run before React commits the updated UI, so use an effect or ref callback to focus an element that appears after submission.
 
-Callbacks can return `Promise<void>`. The Action awaits them, and `form.pending` stays true until they complete. Errors thrown or rejected by callbacks reach the nearest React error boundary. Aborted submissions invoke neither callback.
+If a callback awaits `router.visit()` or `router.refresh()`, pass `{ resolveOn: 'data' }` so it can finish before React commits the navigation. See [React navigation completion](../../reference/api/pages.md#react-navigation-completion).
 
 Vue, Svelte, and Solid submissions return a promise instead; use `await form.post()` to run work after a submission.
 
+### Scroll after submission
+
+Actions and forms keep the current scroll position when updating the page in place. Redirects and submissions that open another page scroll to the top, or to the destination's hash target.
+
+Pass `preserveScroll: false` to reset scroll after an in-place update, or `true` to keep it even after a redirect:
+
+```ts
+await action('/users/:id?update', {
+  params: { id: '42' },
+  data: { name: 'Alice' },
+  preserveScroll: false,
+});
+```
+
+In React, set `preserveScroll` in the third argument to `useForm()`. In Vue, Svelte, and Solid, pass it to the submit method, such as `form.post({ preserveScroll: false })`.
+
 ## Named Actions
 
 When a page needs multiple mutations, such as updating and deleting a user on the same page, export `actions` (plural) instead of `action`:
 
 ```ts
-import { users, updateUserSchema } from '@schema';
 // pages/users/[id].server.ts
+import { users, updateUserSchema } from '@schema';
 import { defineHandler } from 'void';
 import { db, eq } from 'void/db';
 
@@ -227,7 +244,7 @@ export const actions = {
 };
 ```
 
-Named actions are dispatched via a `?actionName` suffix on the URL (e.g. `/users/42?update`). The client primitives `useForm` and `action()` handle this automatically. The action key stays out of the page URL. When `POST /users/42?update&tab=profile` renders the page again, `useForm` and `action()` leave the address bar at `/users/42?tab=profile`, and `c.redirect('/users/42')` goes to `/users/42?tab=profile`.
+Named actions use a `?actionName` suffix, such as `/users/42?update`. `useForm` and `action()` handle this automatically. After a POST action renders the page or uses a default `c.redirect()`, the page URL keeps ordinary query parameters: `/users/42?update&tab=profile` becomes `/users/42?tab=profile`. See [redirect query parameters](../../reference/api/rewrites.md#c-rewrite-destination) for redirects that preserve the request method.
 
 Use `action` or `actions` in a file, not both.
 
@@ -273,7 +290,7 @@ if (!result.ok) {
 
 `action()` defaults to `POST`. Pass `data`, `params`, and `method` to set the body, route parameters, or HTTP method.
 
-A successful call returns `{ ok: true, pageData }`. Expected errors, such as validation failures or conflicts, return `{ ok: false, error }`.
+A successful call returns `{ ok: true, pageData }`. Expected errors, such as validation failures or conflicts, return `{ ok: false, error }`. `error.message` is the message of an [`HTTPException`](../../integrations/hono.md#utilities) with a `4xx` status, or the body of another plain-text `4xx` response. For other errors, it is a status summary such as `Action failed with 404 Not Found`.
 
 ## Validation Errors
 

package/docs/guide/pages-routing/islands.md

@@ -96,11 +96,11 @@ export default function BlogIndex({ posts }) {
 
 ```vue [Vue]
 <!-- pages/blog/index.island.vue -->
-<script setup>
+<script setup lang="ts">
 import Counter from './_Counter.vue' with { island: 'load' };
 import PostForm from './_PostForm.vue' with { island: 'visible' };
 
-defineProps({ posts: Array });
+const { posts } = defineProps<{ posts: { slug: string; title: string }[] }>();
 </script>
 
 <template>
@@ -135,8 +135,8 @@ let { posts } = $props();
 ```
 
 ```tsx [Solid]
-import { For } from 'solid-js';
 // pages/blog/index.island.tsx
+import { For } from 'solid-js';
 import Counter from './_Counter' with { island: 'load' };
 import PostForm from './_PostForm' with { island: 'visible' };
 
@@ -209,7 +209,7 @@ After a successful action, an island page reloads or redirects through `window.l
 
 ## Forms
 
-Island pages cannot use `useForm` because it depends on the Void Router. Use `useIslandForm` instead. It has the same form state, but its submit helpers take the action URL and use `fetch()` directly:
+Use `useIslandForm` for forms in island components. It provides the same form state as `useForm`, and its submit helpers take the action URL:
 
 ::: code-group
 
@@ -249,7 +249,7 @@ export default function PostForm() {
 ```
 
 ```vue [Vue]
-<script setup>
+<script setup lang="ts">
 import { useIslandForm } from '@void/vue';
 
 const form = useIslandForm({ title: '', body: '' });

package/docs/guide/pages-routing/layouts.md

@@ -167,7 +167,7 @@ export default function Page() {
 ```
 
 ```vue [Vue]
-<script>
+<script lang="ts">
 export const layout = 'landing';
 </script>
 
@@ -238,4 +238,18 @@ export default defineMiddleware(async (c, next) => {
 });
 ```
 
-Call `useShared()` from your framework adapter, as in the layout examples above. Its return type is inferred from `CloudContextVariables`. Shared data comes from middleware; page props come from the loader. See [Context variables](../type-safety.md#context-variables).
+Call `useShared()` from your framework adapter, as in the layout examples above. Its return type is inferred from `CloudContextVariables`. See [Context variables](../type-safety.md#context-variables).
+
+Middleware sets the starting value. A loader or action can update it before the page is sent:
+
+```ts
+// pages/profile.server.ts
+import { defineHandler } from 'void';
+
+export const action = defineHandler(async (c) => {
+  const user = await updateProfile(c);
+  c.set('shared', { ...c.get('shared'), auth: { user } });
+});
+```
+
+Middleware runs before the action. If an action changes data that shared data is built from, update shared data in the action, or redirect with `c.redirect()` so middleware runs again on the next page load.

package/docs/guide/pages-routing/loaders.md

@@ -11,8 +11,8 @@ A loader fetches the data a page needs. Define it in a companion `.server.ts` fi
 `loader` runs on GET requests and returns an object that becomes the page's props:
 
 ```ts
-import { users } from '@schema';
 // pages/users/index.server.ts
+import { users } from '@schema';
 import { defineHandler } from 'void';
 import type { InferProps } from 'void';
 import { db } from 'void/db';
@@ -51,7 +51,7 @@ export default function UsersPage({ users }: Props) {
 <!-- pages/users/index.vue -->
 <script setup lang="ts">
 import type { Props } from './index.server';
-defineProps<Props>();
+const { users } = defineProps<Props>();
 </script>
 
 <template>
@@ -79,8 +79,8 @@ defineProps<Props>();
 ```
 
 ```tsx [Solid]
-import { For } from 'solid-js';
 // pages/users/index.tsx
+import { For } from 'solid-js';
 import type { Props } from './index.server';
 
 export default function UsersPage(props: Props) {
@@ -102,8 +102,8 @@ export default function UsersPage(props: Props) {
 Use `defer()` for slow data. The page renders immediately and receives the result when it is ready:
 
 ```ts
-import { projects } from '@schema';
 // pages/dashboard.server.ts
+import { projects } from '@schema';
 import { defineHandler, defer } from 'void';
 import type { InferProps } from 'void';
 import { db } from 'void/db';
@@ -177,7 +177,7 @@ Check `loading` first, then `error`. TypeScript narrows `value` to `T` in the re
 ```vue [Vue]
 <script setup lang="ts">
 import type { Props } from './dashboard.server';
-defineProps<Props>();
+const { projects, usage } = defineProps<Props>();
 </script>
 
 <template>

package/docs/guide/pages-routing/markdown.md

@@ -64,9 +64,9 @@ Add the plugin to your Vite config **after** the framework adapter:
 ::: code-group
 
 ```ts [React]
+// vite.config.ts
 import { voidMarkdown } from '@void/md/plugin';
 import { voidReact } from '@void/react/plugin';
-// vite.config.ts
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -76,9 +76,9 @@ export default defineConfig({
 ```
 
 ```ts [Vue]
+// vite.config.ts
 import { voidMarkdown } from '@void/md/plugin';
 import { voidVue } from '@void/vue/plugin';
-// vite.config.ts
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -88,9 +88,9 @@ export default defineConfig({
 ```
 
 ```ts [Svelte]
+// vite.config.ts
 import { voidMarkdown } from '@void/md/plugin';
 import { voidSvelte } from '@void/svelte/plugin';
-// vite.config.ts
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -100,9 +100,9 @@ export default defineConfig({
 ```
 
 ```ts [Solid]
+// vite.config.ts
 import { voidMarkdown } from '@void/md/plugin';
 import { voidSolid } from '@void/solid/plugin';
-// vite.config.ts
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -190,7 +190,7 @@ export default function DocsLayout({ children }) {
 ```
 
 ```vue [Vue]
-<script setup>
+<script setup lang="ts">
 import { useFrontmatter } from '@void/md';
 
 const fm = useFrontmatter();
@@ -230,7 +230,7 @@ export default function DocsLayout(props) {
 
 :::
 
-Island components on a Markdown page can call `useFrontmatter()` too. A page with islands includes its frontmatter in the HTML for them to read in the browser. Keep private values out of the frontmatter of those pages.
+Island components can also call `useFrontmatter()`. Keep frontmatter on pages with islands safe to share with the browser.
 
 ## Pages Virtual Module
 
@@ -241,7 +241,7 @@ import pages from '@void/md/pages';
 // [{ path: "/docs/getting-started", title: "Getting Started", frontmatter: {...}, headings: [...] }, ...]
 ```
 
-The list holds only the pages for the current [environment](./overview.md#environment-only-pages): `.dev` pages on the dev server, `.prod` pages in builds. The suffix is dropped from `path`: `debug.dev.md` is listed as `/debug`.
+The list follows [page environment suffixes](./overview.md#environment-only-pages): `debug.dev.md` appears as `/debug` during development.
 
 Each entry has this shape:
 

package/docs/guide/pages-routing/overview.md

@@ -41,8 +41,8 @@ Add both plugins to your Vite config:
 ::: code-group
 
 ```ts [React]
-import { voidReact } from '@void/react/plugin';
 // vite.config.ts
+import { voidReact } from '@void/react/plugin';
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -52,8 +52,8 @@ export default defineConfig({
 ```
 
 ```ts [Vue]
-import { voidVue } from '@void/vue/plugin';
 // vite.config.ts
+import { voidVue } from '@void/vue/plugin';
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -63,8 +63,8 @@ export default defineConfig({
 ```
 
 ```ts [Svelte]
-import { voidSvelte } from '@void/svelte/plugin';
 // vite.config.ts
+import { voidSvelte } from '@void/svelte/plugin';
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -74,8 +74,8 @@ export default defineConfig({
 ```
 
 ```ts [Solid]
-import { voidSolid } from '@void/solid/plugin';
 // vite.config.ts
+import { voidSolid } from '@void/solid/plugin';
 import { defineConfig } from 'vite';
 import { voidPlugin } from 'void';
 
@@ -94,16 +94,9 @@ Pages can be flat files such as `about.vue` or directory-based routes such as `a
 
 <PagesFileTree />
 
-Keep one file per route. Void reports an error when two page files resolve to the same path, such as `about.vue` and `about/index.vue`, or the same page in two route groups.
+Use one page file per URL in each environment.
 
-Each page can have a companion `.server.ts`, `.server.tsx`, `.server.js`, `.server.jsx`, `.server.mts`, or `.server.mjs` file that runs exclusively on the server. Use `.server.tsx` or `.server.jsx` when the companion contains JSX (see [JSX handlers](../server-routing.md#jsx-handlers) for the JSX runtime). A companion belongs to its matching page and does not create a separate route:
-
-| File                   | Role                           |
-| ---------------------- | ------------------------------ |
-| `pages/foo.tsx`        | Page component at `/foo`       |
-| `pages/foo.server.tsx` | Server companion for that page |
-
-A companion can export:
+Pair a page with a `.server.ts` file for server code, such as `about.server.ts` for `about.vue`. Companions also support `.js`, `.mts`, `.mjs`, and [JSX](../server-routing.md#jsx-handlers) with `.tsx` or `.jsx`. They can export:
 
 - A [**loader**](./loaders), which runs on `GET` and returns the data that becomes the page component's props
 - [**Actions**](./actions-and-forms), which handle mutations from forms and programmatic calls. Export a single `action` or multiple [named actions](./actions-and-forms#named-actions) when a page has several mutations
@@ -113,7 +106,7 @@ File-based routing rules are the same as [server routing](../server-routing.md):
 
 ### Environment-only pages
 
-Add a `.dev` or `.prod` suffix before the extension to include a page in only one environment. The suffix is not part of the URL:
+Add a `.dev` or `.prod` suffix before the extension to choose when a page is available:
 
 ```
 pages/
@@ -126,12 +119,9 @@ pages/
 
 `.dev` pages run only on the dev server; `.prod` pages run in builds, deployments, and production previews.
 
-- A `.dev` page and a `.prod` page can share a URL. A plain page and a suffixed page for the same URL is an error wherever both run: `home.tsx` with `home.dev.tsx` fails on the dev server, and `home.tsx` with `home.prod.tsx` fails the build.
-- The suffix goes **before** `.island`: `chart.dev.island.tsx` is a development-only island page. `chart.island.dev.tsx` is not an island page.
-- A companion repeats the suffix: `home.dev.server.ts` belongs to `home.dev.tsx`.
-- Suffixes apply to page files only. Layouts take no suffix.
-- A resource used only by `.dev` pages and their companions is not provisioned for production.
-- The dev server and builds generate types for their own environment. `void prepare` generates types for both.
+Keep the suffix in companion filenames (`home.dev.server.ts`) and place it before `.island` for island pages (`chart.dev.island.tsx`). Layouts are shared across environments.
+
+Production deploys exclude resources used only by `.dev` pages and their companions. Run `void prepare` to generate types for both environments.
 
 ## How Navigation Works
 
@@ -163,46 +153,54 @@ 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>
 ```
 
 :::
 
+With [`routing.typedRoutes`](../type-safety.md#checked-url-strings), which apps created with `void init` have on, `href` and the router methods below reject plain strings such as `"/user"` that don't match a route.
+
 `Link` also supports query data, history replacement, full-page navigation, and cancellation:
 
 ```tsx
@@ -232,17 +230,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:
@@ -256,12 +265,113 @@ export default function PostPage() {
 }
 ```
 
+### Active links
+
+`Link` marks the link to the current page with `aria-current="page"` and `data-void-active`. Use them to style navigation:
+
+```css
+nav a[data-void-active] {
+  font-weight: 600;
+}
+```
+
+A link is active only on its own path by default. Set `activeMatch="prefix"` to keep it active on nested pages:
+
+::: code-group
+
+```tsx [React]
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/users" activeMatch="prefix">
+    Users
+  </Link>
+</nav>
+```
+
+```vue [Vue]
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/users" active-match="prefix">Users</Link>
+</nav>
+```
+
+```svelte [Svelte]
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/users" activeMatch="prefix">Users</Link>
+</nav>
+```
+
+```tsx [Solid]
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/users" activeMatch="prefix">
+    Users
+  </Link>
+</nav>
+```
+
+:::
+
+| Current URL     | `href="/users"` | `href="/users" activeMatch="prefix"` |
+| --------------- | --------------- | ------------------------------------ |
+| `/users`        | both attributes | both attributes                      |
+| `/users?page=2` | both attributes | both attributes                      |
+| `/users/42`     | none            | `data-void-active`                   |
+| `/users-admin`  | none            | none                                 |
+
+`aria-current="page"` marks only the exact page, so select `[aria-current="page"]` to style it differently from its section. A link to `/` is active only on the home page.
+
+Paths match the way pages are routed: letter case and trailing slashes count, while the query string and hash are ignored. Links to other origins and non-GET links are never active. An `aria-current` or `data-void-active` you pass to `Link` replaces the computed value.
+
+### Pending links
+
+While a page loads, `Link` adds `data-void-pending` to every link to it. Use it to show that a click is being handled:
+
+```css
+a[data-void-pending] {
+  opacity: 0.6;
+  /* Skip visits that finish quickly, such as to a prefetched page */
+  transition: opacity 0.15s 0.1s;
+}
+```
+
+A link is pending only while its exact destination loads. The path, query and hash must all match, so a link to `/users?page=2` isn't pending while `/users?page=3` loads. A non-GET link, which renders a `<button>`, is pending while a request with its method to its `href` runs. `router.refresh()` reloads the current page, so links to it are pending during a refresh.
+
+A `data-void-pending` you pass to `Link` replaces the computed value. For a loading indicator that covers the whole page, use [`useNavigation()`](../../reference/api/pages.md).
+
+### Prefetching
+
+Add `prefetch` to a `Link` to load its page before the user clicks, so the visit doesn't wait for the server:
+
+```tsx
+<Link href="/dashboard" prefetch>
+  Dashboard
+</Link>
+```
+
+`prefetch` on its own loads the page on hover, keyboard focus, or touch. A `Link` can also prefetch on click, as soon as it renders, or once it stays in view, and `cacheFor` sets how long a prefetched page is reused. See [Prefetching](../../reference/api/pages.md#prefetching) for every option.
+
+To give every `Link` a prefetch strategy, set `prefetch.defaultStrategy` in the adapter plugin. A `Link` that sets its own `prefetch` keeps it:
+
+```ts
+// vite.config.ts
+voidReact({ prefetch: { defaultStrategy: 'hover' } });
+```
+
+Prefer `'hover'` or `'click'` as the default. With `'mount'` or `'visible'`, every `Link` loads its page once it renders or stays in view, which adds up in long lists.
+
+`Link` doesn't prefetch while the browser reports that data saver is on or the connection is 2G, which only Chromium-based browsers report.
+
+Prefetching runs the destination's loader, so keep loaders free of side effects such as counting views.
+
 ## Scroll Restoration
 
 Void manages scroll position for Pages automatically:
 
 - **Back/forward navigation and reloads** restore the saved scroll position.
 - **New navigation** scrolls to the top of the page.
+- **Actions and forms** keep scroll when updating the current page. Redirects follow normal navigation behavior.
 - **Hash links** (`/docs#api`) scroll to the target element. Same-page hash links (`#section`) skip the server fetch entirely.
 
 To keep the current scroll position, pass `preserveScroll: true`:

package/docs/guide/platform/administration/connected-apps.md

@@ -16,7 +16,7 @@ Local development permits exact HTTP callbacks on localhost when the platform's
 
 The app sends users to Void's authorization page, where Void displays its registered name, operator, callback origin, and requested permission. Sign-in permits reading the user's ID and username. It does not provide an account token or project management access.
 
-Users can disconnect applications at `<platform API URL>/oauth/connections`. Grants also expire after an hour and become invalid when their platform login session is revoked or their account is suspended. Applications must request a new sign-in when access expires.
+Users can disconnect applications at `<platform API URL>/oauth/connections`. Access tokens expire after an hour, and apps renew them with a refresh token. Refreshing does not extend access past the Void sign-in the user approved the app from: access ends 30 days after that sign-in, or earlier if the sign-in is revoked or the account is suspended. Applications must then ask the user to sign in again.
 
 ## Private previews
 
@@ -48,6 +48,8 @@ Disabling the app or disconnecting its grant stops authorization for subsequent
 
 Discover endpoints at `/.well-known/oauth-authorization-server` on the platform API origin. Use authorization code flow with `scope=profile`, a random `state`, and S256 PKCE. Authenticate token exchanges using HTTP Basic client authentication. Send access tokens as Bearer credentials to `/oauth/userinfo`; its response contains `sub`, `preferred_username`, and the consented `scope`.
 
+The code exchange also returns a `refresh_token`. To renew access, POST `grant_type=refresh_token` and `refresh_token` to `/oauth/token` with client Basic authentication. The response has a new access token and a new `refresh_token`; store the new one and discard the old. Each refresh token works once: sending a used one again revokes the connection and the user must reconnect, so send one refresh at a time per connection. Store refresh tokens as securely as access tokens. An optional space-separated `scope` requests fewer permissions than the user approved; the connection keeps the narrower set, and later refreshes cannot widen it. `deploy:approve` publish tokens never come with a refresh token, so each publish still needs its own approval.
+
 For publishing, package the built app with [`prepareDeployArtifact`](/reference/api/deploy). POST to `/oauth/deployment-requests` using the profile token:
 
 ```ts
@@ -66,6 +68,6 @@ Redirect the browser to the returned `authorization_url`. Exchange its code with
 
 Use the token to request URLs from `POST /projects/:id/deploy/upload-urls`, upload the declared assets, and send the artifact to `POST /projects/:id/deploy`. Set `x-void-deploy-idempotency-key` to `approval_id`. Deployment uses Void's managed deployment protocol and requires the platform deployment Queue. The credential cannot read secrets, mint project tokens, delete projects, or deploy different bytes.
 
-Revoke identity grants with `POST /oauth/revoke`, authenticated as the client. No refresh token or OpenID Connect ID token is issued.
+Revoke a connection with `POST /oauth/revoke`, authenticated as the client, using either its access token or its refresh token. Void does not issue an OpenID Connect ID token.
 
 If the API is protected by Cloudflare Access, the application operator must also configure a service identity permitted by that Access application's policy. Server OAuth endpoints and approved deployment requests still validate their own client, grant, and project authority; browser consent requires the user's company identity.

package/docs/guide/platform/administration/email.md

@@ -10,7 +10,7 @@ These commands apply to a platform that enables email. Every project can send fr
 
 Shared inbound mail uses one exact routing rule per receiving project and enables Cloudflare’s per-zone plus addressing. Creating a project or deploying an app that only sends mail consumes no inbound rule. Existing rules and the apex catch-all remain in place. Cloudflare normally allows [200 routing rules per domain](https://developers.cloudflare.com/email-service/platform/limits/); remove unused rules or request a higher limit if the shared domain reaches capacity. An unrelated rule for a project’s base address or a plus address blocks its setup until that conflict is removed.
 
-A project owner can give the shared address one permanent, shorter name with `void email alias <name>`. A receiving project with an alias uses two rules, one for the slug and one for the alias, because the slug address keeps working. Setting an alias is refused while a conflicting rule exists or the domain is at its rule limit, and the alias is released only when the project is deleted.
+A project owner can set a permanent, shorter address with [`void email alias <name>`](../../../reference/cli/email.md#void-email-alias). Receiving mail at both the slug and alias uses two routing rules. Resolve conflicting rules and check the domain's rule limit before adding an alias.
 
 If recipient creation is interrupted, inspect its retained intent:
 
@@ -31,7 +31,7 @@ for the recovery requirements.
 
 ### Mail that the platform sends {#platform-sender}
 
-The platform sends its own mail, for example invitations, welcome mail, failed-deploy notices, and error alerts. This mail comes from `noreply@<mail domain>`, and the sender name is the platform's display name. Void sets this sender, so you do not need to configure one. Do not set a different sender on the platform Workers in the Cloudflare dashboard. That change stops the next `upgrade`, `repair`, `enable`, or `rollback` until you let Void replace it. See [Platform Workers changed outside Void](/guide/platform/installation/maintenance#workers-changed-outside-void).
+Platform invitations, welcome mail, and deployment alerts use `noreply@<mail domain>` with the platform's display name. Void configures this sender automatically.
 
 Mail to an address that is not verified needs Cloudflare Email Sending onboarding and [Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans).
 
@@ -161,10 +161,8 @@ If an apex already receives mail with another provider, such as Microsoft 365 or
 void platform email domain-add brand.example --project hr-portal --outbound-only
 ```
 
-The project can then send from any address on the apex, such as `support@brand.example`. It cannot receive mail there: the MX records, the apex SPF record, and incoming mail stay with the current provider.
+The project can then send from any address on the apex, such as `support@brand.example`. Incoming mail, MX records, and the apex SPF record stay with your current provider.
 
-- Cloudflare Email Sending must be available, which needs Workers Paid. Without it, setup is blocked instead of falling back to verified destinations only. Upgrade, then run `domain-sync`.
-- Email Sending adds its own records on `cf-bounce.<domain>` and `_dmarc.<domain>`. If Cloudflare reports that existing records conflict with them, for example several DMARC records, setup is blocked and the error lists each record. Fix them, then run `domain-sync`.
-- Only administrators can register an outbound-only domain, and it must be a zone apex. The platform's shared mail zone cannot be outbound-only.
-- `domain-rotate-secret` does not apply. `domain-remove` stops sending through the platform and leaves the MX records alone.
-- To switch an outbound-only domain to platform-managed inbound mail, or back, remove it first and add it again.
+This requires [Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans) and Cloudflare Email Sending onboarding. Email Sending adds records at `cf-bounce.<domain>` and `_dmarc.<domain>`. Resolve any reported DNS conflicts, then run `domain-sync`.
+
+Only administrators can register outbound-only domains. Choose a zone apex separate from the platform's shared mail zone. Use `domain-remove` to stop sending through the platform. To change between outbound-only and platform-managed inbound mail, remove the domain and add it again.