void 1.3.0 → 1.5.0

package/docs/guide/auth.md

@@ -119,7 +119,7 @@ import { getSession, getUser, requireAuth } from 'void/auth';
 - `getSession()` returns `{ user, session } | null`
 - `requireAuth(c)` returns the authenticated user or throws `401`
 
-Import `AuthUser` and `AuthSession` from `void/auth` for type annotations. See their fields in the [API reference](../reference/api/auth.md#authuser).
+Import `AuthUser` and `AuthSession` from `void/auth` for type annotations. They include the fields your Better Auth plugins and `user.additionalFields` add, such as `role` from `admin()`. See their fields in the [API reference](../reference/api/auth.md#authuser).
 
 ## Behavior
 

package/docs/guide/database.md

@@ -56,8 +56,8 @@ Define your tables in `db/schema.ts` using column helpers from `void/schema-d1`,
 ::: code-group
 
 ```ts [SQLite (D1)]
-import { sql } from 'void/db';
 // db/schema.ts
+import { sql } from 'void/db';
 import { sqliteTable, text, integer } from 'void/schema-d1';
 
 export const users = sqliteTable('users', {
@@ -314,8 +314,8 @@ export const insertUserSchema = createInsertSchema(users, {
 ```
 
 ```ts [Valibot]
-import { pipe, minLength, email } from 'valibot';
 // db/schema.ts
+import { pipe, minLength, email } from 'valibot';
 import { createInsertSchema } from 'void/drizzle-valibot';
 
 export const insertUserSchema = createInsertSchema(users, {
@@ -325,8 +325,8 @@ export const insertUserSchema = createInsertSchema(users, {
 ```
 
 ```ts [ArkType]
-import { type } from 'arktype';
 // db/schema.ts
+import { type } from 'arktype';
 import { createInsertSchema } from 'void/drizzle-arktype';
 
 export const insertUserSchema = createInsertSchema(users, {
@@ -342,8 +342,8 @@ export const insertUserSchema = createInsertSchema(users, {
 Use the derived schema in your route handlers with [`withValidator()`](./server-routing.md#validation):
 
 ```ts
-import { users, insertUserSchema } from '@schema';
 // routes/api/users/index.ts
+import { users, insertUserSchema } from '@schema';
 import { defineHandler } from 'void';
 import { db } from 'void/db';
 

package/docs/guide/deployment.md

@@ -35,7 +35,7 @@ void db generate
 
 Review and commit the SQL, then deploy again. Rollback does not reverse database migrations. See [Database](./database.md) for the local workflow.
 
-On your own Cloudflare account, deploy saves a D1 [Time Travel](https://developers.cloudflare.com/d1/reference/time-travel/) restore point before it applies pending migrations and prints the [`void db restore`](../reference/cli/database.md#void-db-restore) command for it. If no restore point can be saved, deploy stops before it migrates. If deploy fails after it applied the migrations, for example when the upload fails, it prints the command again. Usually you fix the error and deploy again; restore only if the live version cannot run against the new schema. To recover from a bad migration, roll back the code with `void project rollback` if the new version is live, restore the database, then fix or remove the migration before you deploy again. After a one-off `void deploy --platform cloudflare`, add `--platform cloudflare` to each of these commands. Restoring discards every write made after the restore point. Restore points expire after 7 days on Workers Free and 30 days on Workers Paid; after that, undo a migration with a new one.
+For D1 on your own Cloudflare account, deploy saves a restore point before applying migrations and prints a [`void db restore`](../reference/cli/database.md#void-db-restore) command. Use it to recover from a bad migration, then fix the migration before deploying again. A restore discards writes made after that point; check that your deployed code works with the restored schema. See the command reference for the recovery steps and retention limits.
 
 ### Environment variables
 

package/docs/guide/edge/headers.md

@@ -35,13 +35,9 @@ Header rules do not apply to ISR cache responses.
 
 ### Cookie headers
 
-On a [Void platform](../deployment.md#deploy-to-a-team-platform), apps usually share an application domain, such as `apps.example.com`. Header rules on a platform deploy change two headers on all hostnames of the app, including custom domains:
+On a [Void platform](../deployment.md#deploy-to-a-team-platform), set cookies in your app's response. Header rules ignore `Set-Cookie`, remove `"cookies"` from `Clear-Site-Data`, and ignore `Clear-Site-Data` rules containing `"*"`. You can use directives such as `"cache"` and `"storage"` in header rules.
 
-- Void ignores `Set-Cookie` in header rules.
-- Void removes the `"cookies"` directive from `Clear-Site-Data` in header rules. Other directives, such as `"cache"` and `"storage"`, still apply.
-- Void ignores the full value of a `Clear-Site-Data` rule that includes `"*"`. The response then keeps the `Clear-Site-Data` value from your app's response, without `"cookies"`. If that value also includes `"*"`, the response has no `Clear-Site-Data`.
-
-This stops a header rule from setting or clearing cookies for other apps on the same domain. These limits apply only to header rules. Your app's own response can set cookies and send `Clear-Site-Data`, and on a shared domain those can affect other apps. See [Domains and Resources](../platform/installation/domains.md#adding-a-domain).
+These limits apply on all of your app's hostnames, including custom domains, to protect cookies for other apps on the shared domain. Your app's own cookie headers can still affect those apps, so scope cookies carefully. See [Domains and Resources](../platform/installation/domains.md#adding-a-domain).
 
 During local development, with `void deploy --platform cloudflare`, and on [other runtimes](../deployment.md#other-runtimes), header rules apply both headers as written.
 

package/docs/guide/edge/redirects.md

@@ -51,6 +51,28 @@ Path-only sources apply to every domain on the project. Host-prefixed sources ap
 
 The source must use `https://` and a literal hostname without wildcards or a port. Add the domain to your project with `void domain add` before deploying the rule. A domain awaiting certificate verification starts redirecting once it becomes active.
 
+## HTTP to HTTPS
+
+Set `routing.alwaysUseHttps` to redirect HTTP requests to HTTPS:
+
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  routing: {
+    alwaysUseHttps: true,
+  },
+});
+```
+
+Void returns a permanent `308` redirect that preserves the path, query string, and request method. The option defaults to `false`. Localhost and loopback addresses stay on HTTP for local development and previews.
+
+This option requires the Cloudflare target and works for Void apps and static sites on either deployment platform.
+
+For direct Cloudflare deployments, also enable [Always Use HTTPS](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/) on your zone to cover assets served directly by Cloudflare.
+
+For direct Cloudflare deployments of SvelteKit, Nuxt, Astro, Analog, TanStack Start, React Router, or vinext, configure HTTPS in the framework or your Cloudflare zone. Use `routing.alwaysUseHttps` only for their static builds, deployed with `--dir` or `inference.appType`.
+
 ## Framework `_redirects` files
 
 Void reads `_redirects` files produced by supported frameworks. You can also place one in Vite's `publicDir`:

package/docs/guide/edge/static-assets.md

@@ -37,16 +37,6 @@ With `void deploy --platform cloudflare`, generated JavaScript bundles with cont
 
 Use [Custom Headers](./headers) to choose a cache policy for other files. Apply immutable caching only to URLs that change whenever their content changes.
 
-Cloudflare serves these fingerprinted JavaScript bundles without starting your Worker, so they do not count as Worker requests, when your app:
-
-- has no global middleware
-- has no header, redirect, rewrite or fallback rules, and no `routing.notFound` setting
-- uses the default `base` of `/`
-- has no route or page that matches paths in the assets directory (`assets/` by default)
-- builds at most 99 fingerprinted bundles
-
-Otherwise these bundles go through your Worker and keep the same caching.
-
 ## Non-hashed assets
 
 Other static files, such as `index.html` and `favicon.ico`, are cached until the next deploy. You do not need to purge them manually.

package/docs/guide/email/domains.md

@@ -16,7 +16,9 @@ void email domain add acme.com
 
 `add` opens a Cloudflare API-token template. Restrict the token to the selected account and mail zone before creating it; Workers Scripts permission applies across that account. The CLI accepts a masked paste or a newly copied token and asks you to confirm those restrictions. The platform encrypts the credential for the zone connection, so projects sharing that zone do not need separate ingress Workers.
 
-Platform-managed custom inbound email requires the apex of a Cloudflare zone. Cloudflare’s catch-all only covers that apex, so a subdomain of the selected zone cannot receive arbitrary addresses. `add` refuses to register a new apex that already has MX records, or whose catch-all already routes elsewhere, so it never takes over mail hosted with another provider such as Microsoft 365 or Google Workspace. Use an apex that has no mail yet, or the platform’s shared mail address. To only send from an apex that keeps its current mail provider, ask your platform administrator to register it as [outbound-only](../platform/administration/email.md#sending-from-a-domain-that-already-receives-mail). Running `add` again for a registered apex, for example to renew its token, keeps working. Each custom apex belongs to one project; a project can register more than one apex.
+For inbound mail, use a Cloudflare zone apex with no existing mail service, such as `example.com`. Each apex belongs to one project, and a project can register several. Existing MX records or a catch-all pointing elsewhere block registration to protect your current mail service.
+
+To keep receiving mail through another provider, ask your platform administrator to register the domain as [outbound-only](../platform/administration/email.md#sending-from-a-domain-that-already-receives-mail). You can also use the platform's shared mail address.
 
 If setup is interrupted, use `void email domain status <domain>` to inspect the saved operation before retrying.
 

package/docs/guide/email/receiving.md

@@ -94,15 +94,15 @@ deployed `email/` handlers without per-project DNS setup once the platform has v
 handlers once its inbound readiness is `ready`. Use `void email domain status`
 to check current provider routing and any remaining setup steps.
 
-A project with an [email alias](../../reference/cli/email.md#void-email-alias) also receives at `<alias>+anything@<mail domain>`. Routing ignores which prefix was used: with the slug `acme-store` and the alias `acme`, both `acme-store+support@…` and `acme+support@…` reach `email/support.ts`.
+A project with an [email alias](../../reference/cli/email.md#void-email-alias) also receives at `<alias>+anything@<mail domain>`. For example, both `acme-store+support@…` and its alias `acme+support@…` reach `email/support.ts`.
 
 For direct deployments, follow [Your own Cloudflare account](./domains.md#your-own-cloudflare-account) to configure inbound addresses.
 
-The local dev server provides the outbound email inbox but has no inbound email trigger. Test inbound handlers with `createInboundTestHarness` below.
+Test inbound handlers locally with `createInboundTestHarness` below.
 
 ## Testing inbound handlers {#testing-inbound-handlers}
 
-Use `createInboundTestHarness` to capture replies, forwards, and rejections. For shared platform mail, pass the full address including the project prefix, such as [`acme+support+abc-123@acme.dev`](mailto:acme+support+abc-123@acme.dev). For direct Cloudflare mail, set `slug: null` and use [`support+abc-123@mail.acme.com`](mailto:support+abc-123@mail.acme.com).
+Use `createInboundTestHarness` to capture replies, forwards, and rejections. For shared platform mail, pass the full address including the project prefix, such as `acme+support+abc-123@acme.dev`. For direct Cloudflare mail, set `slug: null` and use `support+abc-123@mail.acme.com`.
 
 ```ts
 import { describe, it, expect } from 'vitest';

package/docs/guide/email/sending.md

@@ -195,7 +195,7 @@ The inbox keeps the most recent 100 messages through HMR and clears on a full se
 
 The dev inbox works in native Void apps, TanStack Start, and React Router. It is unavailable in SvelteKit, Nuxt, Analog, and Astro; sends from those apps return `BINDING_MISSING`. Use `createEmailTestHarness` from `void/email/testing` to capture sends in tests. If a configured inbox cannot be reached, `sendEmail` returns `UPSTREAM_ERROR` without sending.
 
-`sendInDev` is deprecated. During local development it skips the inbox and returns `BINDING_MISSING`, so it never delivers. Remove it, and deploy the app to test real delivery.
+Remove the deprecated `sendInDev` option to use the local inbox. Deploy the app to test real delivery.
 
 ## Testing {#testing}
 

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';
 
@@ -163,7 +163,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,15 +175,36 @@ 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
+
+In React, pass `onSuccess` and `onError` to `useForm()` to respond to a submission:
+
+```tsx
+const form = useForm(
+  '/users',
+  { name: '', email: '' },
+  {
+    onSuccess: () => setDialogOpen(false),
+    onError: (error) => {
+      console.error(error);
+    },
+  },
+);
+```
+
+`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.
+
+Vue, Svelte, and Solid submissions return a promise instead; use `await form.post()` to run work after a submission.
 
 ## 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';
 
@@ -203,7 +224,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.
 

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

@@ -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
 

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';
@@ -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';

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

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.

package/docs/guide/platform/installation/credentials.md

@@ -70,7 +70,7 @@ Void checks access before provisioning. If it reports a missing permission, upda
 
 Choose a shared sender domain and its Cloudflare zone ID. The mail zone may differ from the application zone, but it must belong to the platform's Cloudflare account.
 
-Before you enable email, enable [Cloudflare Email Routing](https://developers.cloudflare.com/email-service/get-started/route-emails/) for the exact shared sender domain and confirm that its MX records point to Cloudflare. For a subdomain, add that name under the zone's **Email Routing → Settings → Subdomains**. Cloudflare adds the required MX and SPF records. The installer's shared-mail bootstrap verifies those records; it does not add them. Keep existing mail-provider records on other domain names in place.
+Before enabling platform email, configure [Cloudflare Email Routing](https://developers.cloudflare.com/email-service/get-started/route-emails/) for the shared sender domain. For a subdomain, add it under **Email Routing → Settings → Subdomains**. Let Cloudflare add the required MX and SPF records, then confirm that the domain's MX records point to Cloudflare.
 
 Enabling email lets administrators [register email domains for projects](/guide/platform/administration/email#registering-email-domains-for-projects) and lets projects register destination addresses through the runtime token. The runtime token needs these permissions:
 
@@ -86,7 +86,7 @@ The zone permissions must include each zone that will carry mail, including the
 
 For a new installation, set `VOID_EMAIL_SENDER_DOMAIN` and `VOID_EMAIL_SHARED_ZONE_ID` before `void platform install`. The runtime-token link then preselects these permissions.
 
-For an existing installation, add the permissions to its runtime token first. Edit the token in the Cloudflare dashboard. The token value stays the same. Or set `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` to a new token that has all runtime permissions. Then run:
+For an existing installation, edit its runtime token's permissions in Cloudflare, or supply a replacement with `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`. Then run:
 
 ```sh
 VOID_EMAIL_SENDER_DOMAIN=mail.example.com \
@@ -94,13 +94,13 @@ VOID_EMAIL_SHARED_ZONE_ID=your-zone-id \
 void platform upgrade your-installation-id
 ```
 
-Void records the domain and zone for later upgrades; an ordinary upgrade cannot replace them.
+Void saves this domain and zone for later upgrades. Choose them for the lifetime of the installation.
 
-Before the CLI changes anything or pauses traffic, it checks that the runtime token can read the mail zone and its Email Routing settings, rules, and addresses. If Cloudflare denies a request, the command stops and names each missing permission. Void keeps a saved runtime token, so you can add the permission to the same token and run the command again. The check cannot confirm Edit access or Email Sending, so select those permissions as the table shows.
+If setup reports a missing permission, add it to the runtime token and rerun the command. Select all permissions in the table, including Edit access and Email Sending.
 
-Without `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`, `upgrade`, `repair`, `enable`, and `rollback` check the runtime token saved on this machine. The platform can use a newer token, for example one set from another machine. If Cloudflare does not accept the saved token, the CLI shows a warning and continues without the check. To check the token that the platform uses, set `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` to it.
+When maintaining the platform from another machine, set `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` to the current runtime token so the CLI checks its permissions.
 
-The installer deploys the email gateway, prepares the shared mail route, and verifies inbound readiness before opening platform traffic. If setup fails, fix the problem that the error names, for example a missing permission, the exact-domain MX records, or a routing conflict. Then run the same install or upgrade command again. A fresh install resumes with `void platform install --resume --name <installation-id>`; it continues the recorded email operation after the configuration is corrected.
+The installer configures the email gateway and shared mail route. If setup fails, fix the reported permission, DNS, or routing problem and rerun the command. Resume a fresh installation with `void platform install --resume --name <installation-id>`.
 
 ## R2 Upload Credentials