npm - @voltro/cli - Versions diffs - 0.1.0 - Mend

@voltro/cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (626) hide show

package/templates/agent-docs/routing.md ADDED Viewed

@@ -0,0 +1,1553 @@
+# Routing
+> Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework.
+---
+<!-- source: en/routing/overview.md -->
+## Overview
+_Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework._
+The web side of a Voltro app uses **file-based routing**: drop a TSX file under `src/pages/`, the CLI discovers it on every boot + save, and the file becomes a route. No router config, no manual `<Route>` declarations, no codegen step.
+This section covers everything about how URLs map to React + how Voltro decides when to render, what to ship to the browser, and how to navigate between pages.
+## The shape of it
+```text
+src/pages/
+├── layout.tsx              # outer shell (wraps every page)
+├── error.tsx               # error boundary
+├── loading.tsx             # pending UI
+├── not-found.tsx           # 404 fallback
+├── index.tsx               # /
+├── about.tsx               # /about
+├── (marketing)/            # route group — no URL segment
+│   ├── layout.tsx          # marketing-scoped layout
+│   └── pricing.tsx         # /pricing
+├── users/
+│   ├── layout.tsx          # users-scoped layout
+│   ├── error.tsx           # users-scoped error boundary
+│   ├── [id].tsx            # /users/:id
+│   └── index.tsx           # /users
+└── docs/
+    └── [...slug].tsx       # /docs/<anything>  (catch-all)
+```
+That's the whole router. No `<Route>`, no `<Switch>`, no `useRoutes`.
+## What's in this section
+- [Pages & dynamic segments](/docs/routing/pages) — file → URL mapping, `[id]`, `[...slug]`, query params
+- [Layouts & route groups](/docs/routing/layouts) — `layout.tsx`, error boundaries, `(group)/` directories
+- [Render modes](/docs/routing/render-modes) — `static` vs `ssr` vs `isr`, when to use each
+- [Loaders & meta](/docs/routing/loaders-and-meta) — server-side data fetch + `<head>` injection
+- [Navigation](/docs/routing/navigation) — `Link`, `useNavigate`, prefetch on hover
+- [Islands](/docs/routing/islands) — hydrating only the interactive bits, JS-free pages
+## Architecture in one paragraph
+The framework generates a `.framework/app.tsx` on every boot that imports each `*.tsx` file under `src/pages/` (excluding `node_modules`), wraps them in their layout chains, and produces a `<Router routes={…} />` element. A `mount(App, { group })` call in `.framework/main.tsx` mounts it via `react-dom/client`'s `createRoot` (or `hydrateRoot` for SSR pages). The router watches `window.location` + intercepts `<Link>` clicks for client-side nav.
+You don't write any of this. The CLI regenerates it on every save in dev; the build pipeline freezes it for production.
+## Embedding the runtime in a foreign host
+To mount Voltro's reactive runtime *inside* an app that owns its own routing (a Next.js / Remix / existing React shell), skip the generated boot and use the embeddable provider from the light `@voltro/web/runtime` subpath:
+```tsx
+import { VoltroRuntimeProvider, type MountedApi } from '@voltro/web/runtime'
+const apis: ReadonlyArray<MountedApi> = [
+  { name: 'app', group, descriptors, wsUrl: 'wss://your-api.example.com/ws' },
+]
+export const Providers = ({ children }: { children: React.ReactNode }) => (
+  <VoltroRuntimeProvider apis={apis}>{children}</VoltroRuntimeProvider>
+)
+```
+Inside it, every `@voltro/client` hook (`useSubscription`, `useMutation`, `useAction`, …) resolves exactly as in a native Voltro app — it builds + supervises the per-api RpcClient-over-WebSocket + runtime + subscription cache and handles reconnect. `children` render immediately (a pending api reads `undefined` until connected — no spinner gate), so a prerendered host hydrates without a mismatch. The `@voltro/web/runtime` subpath pulls only the rpc/socket/runtime graph, not the router/mount/SSR — keeping the host bundle small. (`FrameworkBoot`, the framework's own web boot, is a thin wrapper over this provider.) Consume the framework as the **published** package — a `file:` link to an unbuilt checkout resolves the raw `src` export, which a foreign bundler can't handle.
+## Conventions
+| Pattern | Behaviour |
+|---|---|
+| `index.tsx` in a directory | Maps to the directory's URL (no segment for the filename). |
+| `[name].tsx` | Dynamic single segment. Available via `useParams<{ name: string }>()`. |
+| `[...rest].tsx` | Catch-all. `useParams<{ rest: string }>()` joins the captured path with `/`. |
+| `[[...rest]].tsx` | Optional catch-all. Matches both `/foo` and `/foo/bar/baz`. |
+| `(name)/` | Route group. Strips the segment from the URL but layouts inside still apply. |
+| `_*.tsx` | Private — discovery skips it. Useful for helpers next to pages. |
+| `*.island.tsx` | Hydration island. Bundles as a separate chunk; hydrated only when imported. |
+## When NOT to use file-based routing
+The pattern works for ~99% of apps. Edge cases:
+- **Programmatically generated routes** — when you can't know the URL ahead of time. Use `[...slug].tsx` + match inside.
+- **i18n with URL-segment locale** — see [URL strategies](/docs/i18n/url-strategies) for the shipped URL-prefix approach (`/de/docs/foo`).
+- **Cross-tenant subdomains** — handled at the reverse-proxy layer; the file-based router serves one host's paths.
+For everything else, drop a file + done.
+## Where to next — building the UI inside the page
+Routing gets you to a page; the **[Schema-driven UI](/docs/ui/overview)** section
+fills it. It's the other half of the frontend story:
+- **[Forms & tables](/docs/ui/forms-and-tables)** — `<AutoForm>` binds to a
+  mutation, `<DataTable>` to a query; fields + columns come from the
+  descriptors' `effect/Schema`, validation + live auto-optimistic for free.
+- **[Reactive components](/docs/ui/reactive-components)** — drop-in workflow
+  progress, presence/multiplayer, and AI chat over the durable backend.
+- **[Client utilities](/docs/ui/client-utilities/use-can)** — the bound-hook toolbox
+  beyond `useSubscription`/`useMutation`: `useCan`, `useDerived`, `usePreview`,
+  `useUndo`, `useProvenance`, `useAsyncValidation`, `useOutbox`,
+  `useWindowedSubscription`, and more.
+---
+<!-- source: en/routing/pages.md -->
+## Pages & dynamic segments
+_Filesystem → URL mapping, dynamic [id] segments, catch-all [...slug] queries, query params, and private files._
+A **page** is any `*.tsx` file under `src/pages/` that's not a special file (`layout.tsx`, `error.tsx`, `loading.tsx`, `not-found.tsx`) and doesn't start with `_`. Its default export is the page component; the URL comes from the file path.
+## A static page
+```tsx
+// src/pages/about.tsx → /about
+import type { ReactNode } from 'react'
+export default function About(): ReactNode {
+  return (
+    <div className="max-w-2xl mx-auto py-12 px-6">
+      <h1 className="text-3xl font-bold">About us</h1>
+      <p>Voltro Cloud is a framework for shipping multi-tenant SaaS.</p>
+    </div>
+  )
+}
+```
+That's it. Save the file, the CLI's discovery sees it on next save, the page is live at `/about`.
+## index files
+`index.tsx` maps to the directory's URL:
+```text
+src/pages/index.tsx         → /
+src/pages/users/index.tsx   → /users
+src/pages/admin/index.tsx   → /admin
+```
+## Dynamic segments
+Brackets in the filename are dynamic. The captured value comes through `useParams<T>()`:
+```tsx
+// src/pages/users/[id].tsx → /users/:id
+import { useParams } from '@voltro/web'
+export default function User() {
+  const { id } = useParams<{ id: string }>()
+  return <h1>User {id}</h1>
+}
+```
+Multiple dynamic segments in one path:
+```text
+src/pages/orgs/[orgId]/projects/[projectId].tsx
+// → /orgs/:orgId/projects/:projectId
+const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
+```
+## Catch-all queries
+`[...name]` captures one OR more URL segments as a single param value (joined by `/`):
+```tsx
+// src/pages/docs/[...slug].tsx → /docs/<anything>
+const { slug } = useParams<{ slug: string }>()
+// /docs/intro/getting-started → slug = "intro/getting-started"
+```
+**Optional** catch-all (matches the base URL too):
+```tsx
+// src/pages/docs/[[...slug]].tsx
+// /docs       → slug = ""
+// /docs/foo   → slug = "foo"
+// /docs/foo/bar → slug = "foo/bar"
+```
+## Priority
+When multiple files could match (static, dynamic, catch-all), priority is:
+1. Static segments win over dynamic.
+2. Dynamic single (`[id]`) wins over catch-all (`[...slug]`).
+3. Optional catch-all (`[[...slug]]`) wins over required catch-all (`[...slug]`) — the optional form scores as more specific, so it matches first.
+```text
+src/pages/users/index.tsx     # /users → wins for /users
+src/pages/users/[id].tsx       # /users/:id → wins for /users/42
+src/pages/users/new.tsx        # /users/new → wins (static beats dynamic)
+src/pages/[...rest].tsx        # everything else
+```
+## Query strings
+Voltro doesn't bake query params into the query — they're orthogonal to the URL pattern:
+```tsx
+import { useLocation } from '@voltro/web'
+const Page = () => {
+  const pathname = useLocation()
+  // …
+  // For the search string, parse it from the request URL via useServerRequest()
+  // (SSR) or window.location.search (client after hydration).
+}
+```
+For SSR pages that need server-side query parsing:
+```tsx
+import { useServerRequest } from '@voltro/web'
+export const renderMode = 'ssr' as const
+export default function SearchPage() {
+  const req = useServerRequest()
+  const q = req
+    ? new URL(req.url, 'http://x').searchParams.get('q') ?? ''
+    : new URLSearchParams(window.location.search).get('q') ?? ''
+  // …
+}
+```
+Parse the query string explicitly via `useServerRequest()` on the server and `window.location.search` on the client, as shown above.
+## Private files
+Files starting with `_` are skipped by discovery — they're helpers next to pages:
+```text
+src/pages/
+├── _components/
+│   └── UserCard.tsx          # NOT a route — import from siblings
+├── users/
+│   ├── _helpers.ts           # NOT a route
+│   └── [id].tsx              # → /users/:id
+```
+You can also use the colocation pattern: keep page-specific components in a directory named with `_` prefix.
+## Trailing slashes
+The canonical form is **no trailing slash** — always link with `<Link to="/about">`, not `<Link to="/about/">`.
+The framework does NOT emit a trailing-slash redirect on its own. If you need `/about/` → `/about` normalisation (for SEO), configure a 301 redirect at your reverse proxy.
+## What pages CAN'T do
+- **Live outside `src/pages/`.** Discovery walks one root. Helpers + components go elsewhere; pages go here.
+- **Have multiple default exports.** One page per file.
+- **Be `.ts` files.** Pages must be `.tsx` — React components only.
+- **Be discovered via dynamic import.** The CLI generates the import statements at boot; runtime adds need a re-discover (which `voltro dev` does on save).
+## Where to read next
+- [Layouts & route groups](/docs/routing/layouts) — wrap pages in shared chrome
+- [Loaders & meta](/docs/routing/loaders-and-meta) — server-side data + `<head>` tags
+- [Render modes](/docs/routing/render-modes) — `static` / `ssr` / `isr`
+---
+<!-- source: en/routing/layouts.md -->
+## Layouts & route groups
+_layout.tsx, error.tsx, loading.tsx, not-found.tsx, route groups (group)/, and how the chain composes._
+A **layout** wraps every page in its subtree. Drop a `layout.tsx` in a directory and every page below it gets wrapped — outer layouts compose around inner ones automatically.
+The same pattern handles error boundaries (`error.tsx`), pending UI (`loading.tsx`), and 404 fallbacks (`not-found.tsx`). These are the four **special files**; discovery treats them differently from regular pages.
+## Root layout
+```tsx
+// src/pages/layout.tsx — wraps EVERY page
+import type { ReactNode } from 'react'
+import './globals.css'
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <div className="min-h-screen bg-background text-foreground">
+      <header>{/* topbar */}</header>
+      <main>{children}</main>
+      <footer>{/* footer */}</footer>
+    </div>
+  )
+}
+```
+Conventions:
+- **Don't render `<html>`/`<head>`/`<body>`.** The framework's `index.html` shell owns those. Rendering them inside React puts them under `#root` + the browser unwraps them, breaking the document structure.
+- **Set `<html class>` via `theme:` in `app.config.ts`.** Bakes the dark/light class into the shell before first paint.
+- **Set `<title>` + meta via the page's `meta` export.** See [Loaders & meta](/docs/routing/loaders-and-meta).
+## Nested layouts
+```text
+src/pages/
+├── layout.tsx                # outer (every page)
+├── about.tsx                 # /about → wrapped in outer layout
+└── dashboard/
+    ├── layout.tsx            # nested (only /dashboard/*)
+    ├── index.tsx             # /dashboard
+    └── settings.tsx          # /dashboard/settings
+```
+For `/dashboard/settings`, the React tree is:
+```text
+<OuterLayout>
+  <DashboardLayout>
+    <Settings />
+  </DashboardLayout>
+</OuterLayout>
+```
+Outer layouts compose around inner ones. Each layout's state survives navigation **within** its scope — moving from `/dashboard` to `/dashboard/settings` doesn't unmount `DashboardLayout`.
+## Route groups
+A directory in `(parentheses)` does NOT contribute a URL segment, but its layout still applies. Useful when you want a layout for a logical group of pages without nesting their URLs.
+```text
+src/pages/
+├── (marketing)/
+│   ├── layout.tsx            # marketing-scoped chrome
+│   ├── index.tsx             # /
+│   ├── pricing.tsx           # /pricing
+│   └── about.tsx             # /about
+└── (app)/
+    ├── layout.tsx            # authenticated app chrome
+    ├── dashboard.tsx         # /dashboard
+    └── settings.tsx          # /settings
+```
+Marketing pages get one layout; authenticated app pages get another; the URLs stay flat.
+Use this when:
+- The marketing landing + product app share root URL paths but have completely different chrome.
+- You want layout state to NOT persist across logical sections (moving from `/about` to `/dashboard` unmounts everything).
+## Error boundaries
+```tsx
+// src/pages/error.tsx — catches errors from any page below
+import type { ReactNode } from 'react'
+interface ErrorProps {
+  readonly error: Error
+  readonly reset: () => void
+}
+export default function ErrorPage({ error, reset }: ErrorProps): ReactNode {
+  return (
+    <div className="text-center py-12">
+      <h1 className="text-2xl font-bold mb-2">Something went wrong</h1>
+      <p className="text-muted-foreground mb-6">{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )
+}
+```
+- Catches errors from page renders + loaders + any descendant's React tree.
+- `reset()` re-renders the boundary — call after fixing whatever caused the throw.
+- Scoped: `src/pages/dashboard/error.tsx` only catches errors from `/dashboard/*`.
+## Pending UI (opt-in)
+Navigation is **deferred** by default: clicking a link keeps the CURRENT page on screen until the target route's `loader`s settle, then swaps. There is **no full-screen loading overlay**. Background progress shows in the devtools button (dev) or a minimal corner indicator (production) — both read the same status bus.
+`loading.tsx` is an **opt-in** override for one route: export it (or a page-level `Pending`) ONLY when you want that route to swap in immediately and show a skeleton instead of holding the previous page.
+```tsx
+// src/pages/dashboard/loading.tsx — opt-in skeleton for /dashboard/*
+export default function Loading(): ReactNode {
+  return <div className="animate-pulse">Loading…</div>
+}
+```
+`loading.tsx` is driven by in-flight loaders, not by subscriptions — a `useSubscription` returns `data: undefined` until its first snapshot rather than suspending. Render that empty state inside the page itself.
+Scoped like `error.tsx`.
+## Not-found
+```tsx
+// src/pages/not-found.tsx — 404 fallback
+export default function NotFound(): ReactNode {
+  return (
+    <div className="text-center py-12">
+      <h1>Page not found</h1>
+      <a href="/">← Home</a>
+    </div>
+  )
+}
+```
+Scoped: `src/pages/dashboard/not-found.tsx` catches 404s only for URLs starting with `/dashboard/`. Useful for tenant-specific 404 messaging.
+## The default fallback chrome (and localizing it)
+Until you supply your own `error.tsx` / `not-found.tsx`, the router renders a built-in diagnostic chrome — a runtime-error card (error name, stack, Retry / Reload / Copy) and a 404 card. It's a dev-diagnostic surface, not app UI, so it ships full detail regardless of environment. Two ways to change it:
+- **Replace it** — export your own `error.tsx` / `not-found.tsx` (above), or pass `errorFallback` / `notFound` components to the `<Router>`. Total control.
+- **Just relabel it** — wrap the app in `<FallbackStringsProvider>` to override the built-in chrome's English strings without rebuilding the components (e.g. to localize "Retry" / "Reload page" / "No page for this URL"):
+```tsx
+import { FallbackStringsProvider } from '@voltro/web'
+<FallbackStringsProvider
+  strings={{
+    error: { retry: 'Wiederholen', reload: 'Seite neu laden', copy: 'Fehler kopieren' },
+    notFound: { heading: 'Keine Seite für diese URL' },
+  }}
+>
+  {/* your app */}
+</FallbackStringsProvider>
+```
+Overrides deep-merge onto the English defaults — supply only the keys you change; the rest stay English. A per-component `strings` prop on `DefaultErrorFallback` / `DefaultNotFound` wins over the provider for a one-off. (Mirrors `<UiStringsProvider>` for the `@voltro/ui` kit.)
+## How the framework composes them
+For a request to `/dashboard/settings`, the framework walks the page tree:
+1. Find the matching leaf — `dashboard/settings.tsx`.
+2. Walk up the directory tree, collecting every directory's special files in order.
+3. Build the chain: outermost layout → next layout → … → leaf page.
+4. Wrap each layer's `error.tsx` as a React Error Boundary around the next layer.
+5. Render.
+The generated `.framework/app.tsx` records this chain explicitly per route — you can `cat` it to see the result.
+## Limits
+- **One `layout.tsx` per directory.** Multiple would be ambiguous.
+- **Layouts can't be async functions.** Use a `loader` for data + read it via `useLoaderData`.
+- **Error boundaries don't catch loader errors.** Loader errors render the page's `error.tsx`; throwing inside the page's render does too. Both flow through the same boundary.
+- **Layouts can call `useLocation()`, `useParams()`, `useServerRequest()`.** They're React components like any other.
+## Where to read next
+- [Render modes](/docs/routing/render-modes) — how `static` / `ssr` / `isr` interact with layouts
+- [Loaders & meta](/docs/routing/loaders-and-meta) — server-side data + page-level `<head>` tags
+---
+<!-- source: en/routing/render-modes.md -->
+## Render modes
+_static (SSG) vs ssr vs isr — when each runs, what it caches, and how to pick._
+Every page declares a `renderMode`. The mode controls **when** the HTML is produced — at build time, on every request, or build-once-revalidate-occasionally.
+```tsx
+export const renderMode = 'static' as const   // 'static' | 'ssr' | 'isr'
+```
+## The three modes
+| Mode | When HTML is produced | Cached? | Best for |
+|---|---|---|---|
+| `static` *(default)* | `voltro build` time | Forever | Marketing pages, docs, anything that doesn't change per-request |
+| `ssr` | Every request | Never | Authenticated dashboards, search results, anything cookie-driven |
+| `isr` | First request after build, then on revalidate | Per-key in-memory or Postgres | News feeds, listings, dashboards that change but not per-user |
+## static (SSG)
+```tsx
+// src/pages/about.tsx
+export const renderMode = 'static' as const
+```
+At `voltro build`:
+1. The framework runs the page's render once (with `useServerRequest()` returning `null`).
+2. The output HTML lands at `dist/about/index.html`.
+3. `voltro start` serves the file directly — no React runs on the server.
+For dynamic patterns, export `getStaticPaths` to enumerate every URL to pre-render:
+```tsx
+// src/pages/blog/[slug].tsx
+export const renderMode = 'static' as const
+export const getStaticPaths = async () => [
+  { params: { slug: 'first-post' } },
+  { params: { slug: 'second-post' } },
+]
+```
+One HTML file per entry lands in `dist/blog/first-post/index.html` etc.
+Pages that don't enumerate (dynamic without `getStaticPaths`) fall through to the SPA shell — the client-side router takes over.
+## ssr
+```tsx
+export const renderMode = 'ssr' as const
+```
+On every request:
+1. `voltro start` matches the URL → finds your page.
+2. Calls the loader (if any) with the request's params + headers + cookies.
+3. Renders the React tree to HTML.
+4. Returns it.
+Use SSR for:
+- **Authenticated pages** that read the session cookie via `useServerRequest()`.
+- **Personalised content** — recommendations, "your" anything.
+- **Search result pages** — the query string changes per request.
+Cost: every request triggers a fresh render. For very high-traffic pages, prefer ISR.
+### Streaming SSR
+By default an `ssr` page renders with `renderToString` — the whole document is built in memory, then sent. The server-side SSR helpers in `@voltro/web/ssr` also expose a **streaming** path, `renderPageToStream`, built on React's `renderToPipeableStream`. It flushes the shell (and each `<Suspense>` boundary as it resolves) instead of buffering the whole page, so the browser gets the first bytes sooner:
+```ts
+import { renderPageToStream } from '@voltro/web/ssr'
+const { stream, meta } = renderPageToStream({
+  descriptor,
+  params,
+  pathname,
+  loaderData,
+  bootstrapModules: ['/assets/client.js'],
+  onShellReady: () => {
+    // meta is resolved synchronously — write <head> before piping the body.
+    res.setHeader('content-type', 'text/html')
+    res.write(`<!doctype html><html><head>${renderMetaToHtml(meta)}</head><body><div id="root">`)
+    stream.pipe(res)
+  },
+  onAllReady: () => res.end('</div></body></html>'),
+  onShellError: (err) => { res.statusCode = 500; res.end('Internal error') },
+})
+```
+`renderPageToStream` takes the same options as `renderPageToHtml` plus the stream callbacks (`onShellReady` / `onAllReady` / `onShellError`) and `bootstrapModules`. Both paths compose the same providers and resolve `meta` synchronously, so the sync string render and the streaming render produce the same tree — the difference is time-to-first-byte and native Suspense streaming. Most apps never call these directly; the `voltro start` pipeline uses them under the hood.
+## isr (incremental static regeneration)
+```tsx
+export const renderMode = 'isr' as const
+export const revalidate = '60 seconds'   // re-render when older than this
+```
+A bare number is read as **seconds** (Next.js compat) — `revalidate = 60` means 60 seconds, NOT milliseconds. Use the string form (`'60 seconds'`, `'5 minutes'`, `'1 hour'`) for clarity.
+Behaviour:
+| Request | Action |
+|---|---|
+| First | MISS — render, store in cache, serve. |
+| Subsequent (cache fresh) | HIT — serve from cache. |
+| After revalidate window | MISS — re-render, store, serve. |
+| With `staleWhileRevalidate` | STALE — serve cached HTML immediately, kick off background refresh. |
+```tsx
+export const renderMode = 'isr' as const
+export const revalidate = '60 seconds'
+export const staleWhileRevalidate = '60 seconds'   // serve stale while refreshing in bg
+```
+Cache backends:
+- `memory` *(default)* — in-process, doesn't survive restarts.
+- `postgres` — `SSR_CACHE=postgres`. Survives restarts, shared across api instances.
+## Tenant-aware ISR
+For multi-tenant ISR (each tenant gets its own cache entry):
+```tsx
+export const renderMode = 'isr' as const
+export const revalidate = '60 seconds'
+export const tenantAware = true
+```
+The cache key becomes `${pathname}|tenant=${tenant}`, where `tenant` is the request's `x-tenant` header (falling back to `anonymous`). Tenant A's cached HTML never serves to tenant B.
+## CDC-invalidated ISR
+When a specific DB write should invalidate the cache (instead of waiting for the revalidate window):
+```tsx
+export const renderMode = 'isr' as const
+export const cacheInvalidatesOn = ['posts', 'comments']   // tables to watch
+```
+The framework reads Postgres logical replication; writes to `posts` or `comments` invalidate every cached HTML for this query. New requests rebuild the page from the current data.
+Requires `SSR_CACHE=postgres` and a `wal_level=logical` Postgres.
+## Picking between them
+| You have… | Use |
+|---|---|
+| A truly static page (marketing copy) | `static` |
+| A list of known pre-publishable URLs (blog posts) | `static` + `getStaticPaths` |
+| A page that changes per user (dashboard, account) | `ssr` |
+| A search results page (URL query → result) | `ssr` |
+| A blog index that changes when posts are added | `isr` + `cacheInvalidatesOn: ['posts']` |
+| A multi-tenant marketing site (`acme.com/[tenant]/pricing`) | `isr` + `tenantAware: true` |
+| A status page with 30s-stale acceptable | `isr` + `revalidate = '30 seconds'` |
+## What about `interactive`?
+`interactive` is **orthogonal** to `renderMode` — it controls how much JS runs in the browser. See [Islands](/docs/routing/islands).
+| `interactive` | What's hydrated |
+|---|---|
+| `'none'` | Nothing — pure HTML. |
+| `'islands'` | Only `*.island.tsx` files. |
+| `'full'` *(default)* | Whole page. |
+Combinations:
+| `renderMode` × `interactive` | When |
+|---|---|
+| `static` + `none` | Marketing pages, blog posts. Zero JS. |
+| `static` + `full` | SSG with full client-side nav. Docs sites. |
+| `ssr` + `full` | Dashboards. The most "Next.js-like" mode. |
+| `isr` + `islands` | News feeds with a "like" button island. |
+## What gets served when
+A request to `/foo`:
+1. **Pre-rendered HTML exists at `dist/foo/index.html`?** Serve it. (static + isr-already-cached.)
+2. **No pre-render, page is `ssr`?** Render fresh, serve.
+3. **No pre-render, page is `isr`?** Cache lookup → MISS → render → store → serve.
+4. **No pre-render, page is `static`?** Serve the SPA shell — the client router takes over.
+That last case is how dynamic `static` routes work in dev / when `getStaticPaths` didn't include the URL.
+## What doesn't work
+- **Switching `renderMode` per request.** It's a static module export — one value per build.
+- **`renderMode: 'ssr'` without `voltro start`.** SSR requires the production server. Dev mode runs everything client-side regardless.
+- **`isr` with `cacheInvalidatesOn` against memory cache.** Memory cache is per-process; CDC events fire across processes. Use `SSR_CACHE=postgres`.
+## Where to read next
+- [Loaders & meta](/docs/routing/loaders-and-meta) — fetch data before render, inject `<head>` tags
+- [Islands](/docs/routing/islands) — pages that ship 0 JS except for explicit islands
+---
+<!-- source: en/routing/loaders-and-meta.md -->
+## Loaders & meta
+_Server-side data fetch via `loader`, page-level `<head>` tags via `meta`, and how the build pipeline runs both._
+A **loader** is the page's server-side data hook. It runs before the React render (during SSR, during SSG, or per-request for ISR/SSR), and its result lands in `useLoaderData<T>()`. **Meta** is a sibling export that produces `<title>` + `<meta>` tags.
+Both are static module exports — the framework discovers them, the build pipeline runs them.
+## A loader
+```tsx
+// src/pages/notes/[id].tsx
+import { useLoaderData } from '@voltro/web'
+interface Note {
+  readonly id: string
+  readonly title: string
+  readonly body: string
+}
+export const renderMode = 'ssr' as const
+export const loader = async ({ params, headers }: {
+  params: { id: string }
+  headers: Readonly<Record<string, string>>
+}): Promise<Note> => {
+  // Server-side fetch — runs on the Node side, never in the browser.
+  const res = await fetch(`${INTERNAL_API}/notes/${params.id}`, {
+    headers: { cookie: headers.cookie ?? '' },
+  })
+  if (!res.ok) throw new Error(`note ${params.id}: ${res.status}`)
+  return await res.json()
+}
+export default function NotePage(): ReactNode {
+  const note = useLoaderData<Note>()
+  return (
+    <article>
+      <h1>{note.title}</h1>
+      <p>{note.body}</p>
+    </article>
+  )
+}
+```
+`useLoaderData<T>()` returns the loader's resolved value, typed via the generic.
+## When loaders run
+| renderMode | When loader runs |
+|---|---|
+| `static` | At `voltro build` time, once. Result baked into HTML. |
+| `ssr` | Every request. |
+| `isr` | On cache MISS (re-runs when cache stale). |
+For `static` pages with `getStaticPaths`, the loader runs once per enumerated path.
+## Loader arguments
+```ts
+export const loader = async (ctx: {
+  readonly params:   Readonly<Record<string, string>>  // URL params from [name] segments
+  readonly pathname: string                             // matched path (no query string)
+  readonly signal:   AbortSignal                        // Aborts if the client disconnects mid-render
+  readonly headers?: Readonly<Record<string, string>>  // Request headers (SSR/ISR only — empty for SSG/client)
+  // Call the backend rpc directly — present ONLY when the loader runs
+  // server-side (`voltro start` / `voltro dev` SSR); `undefined`
+  // client-side. Resolves a query's FIRST (initial) snapshot.
+  readonly query?: <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>
+}) => Promise<unknown>
+```
+The loader context carries `pathname`, not a `request` object. For the query string during SSR, read it from `useServerRequest().url` inside the component.
+Use `signal` for any fetch that could outlive the request — pass it to `fetch(url, { signal })` so cancelled requests don't waste CPU.
+## Fetching backend data with `ctx.query`
+Instead of hand-rolling a `fetch(INTERNAL_API/...)`, a server-side loader can call the backend rpc directly through `ctx.query` — the same query tags the client subscribes to, resolved to their initial snapshot:
+```tsx
+// src/pages/notes/[id].tsx
+import { useSubscription } from '@voltro/client'
+import { useLoaderData, type PageMeta } from '@voltro/web'
+interface Note { readonly id: string; readonly title: string; readonly body: string }
+export const renderMode = 'ssr' as const
+export const loader = async ({ params, query }: {
+  params: { id: string }
+  query?: <T>(tag: string, input?: Record<string, unknown>) => Promise<T>
+}) => {
+  // `query` is undefined client-side — guard it. SSR forwards the
+  // request's cookie, so the api resolves the SAME Subject + tenant
+  // as the WebSocket path.
+  const note = query ? await query<Note>('notes.get', { id: params.id }) : undefined
+  return { note }
+}
+export const meta = ({ loaderData }: { loaderData: { note?: Note } }): PageMeta => ({
+  title:       loaderData.note ? `${loaderData.note.title} — Notes` : 'Notes',
+  description: loaderData.note?.body.slice(0, 140) ?? '',
+})
+export default function NotePage() {
+  const { note: ssrNote } = useLoaderData<{ note?: Note }>()
+  // Live updates after hydration: useSubscription takes over from the
+  // SSR snapshot. The loader gave us first-paint HTML + correct meta;
+  // the subscription keeps it fresh.
+  const { data } = useSubscription<Note>('app', 'notes.get', { id: ssrNote?.id ?? '' }, { skip: !ssrNote })
+  const note = data ?? ssrNote
+  if (!note) return null
+  return <article><h1>{note.title}</h1><p>{note.body}</p></article>
+}
+```
+Two rules that fall out of this:
+- **`query` is server-only.** It's `undefined` for client-side loader invocations (SPA navigation re-runs the loader in the browser). Guard it (`query ? … : undefined`) and use `useSubscription` in the component for the reactive, after-hydration path. The loader's `query` is for SSR first-paint + `meta`.
+- **It forwards the request cookie.** The HTTP rpc resolves the same Subject + tenant as the WebSocket connection would, so tenant-scoped queries return the right rows during SSR.
+Under the hood, `ctx.query` is a one-shot `POST /rpc` call (see [Wire protocol](/docs/data/wire-protocol#http-one-shot-rpc-post-rpc)).
+## Errors from loaders
+If the loader throws, the framework:
+1. Catches the throw.
+2. Renders the page's `error.tsx` (or the nearest ancestor's) with the error.
+3. Serves the resulting HTML.
+For 404s, throw a `NotFoundError`:
+```ts
+import { NotFoundError } from '@voltro/web'
+export const loader = async ({ params, query }) => {
+  const note = query ? await query('notes.get', { id: params.id }) : undefined
+  if (!note) throw new NotFoundError(`note ${params.id}`)
+  return note
+}
+```
+The framework returns a 404 status + renders `not-found.tsx` for that subtree. The `notFound()` helper is throwing sugar for the same thing — `const note = (await load()) ?? notFound('note ' + params.id)` reads well when the not-found is inline.
+## Meta
+```tsx
+import type { PageMeta } from '@voltro/web'
+export const meta: PageMeta = {
+  title:       'Notes — Voltro',
+  description: 'All your notes, in one place.',
+  tags: [
+    { property: 'og:title',        content: 'Voltro Notes' },
+    { property: 'og:description',  content: 'All your notes, in one place.' },
+    { property: 'og:image',        content: '/og.svg' },
+    { name:     'twitter:card',    content: 'summary_large_image' },
+  ],
+}
+```
+The framework injects these into the HTML's `<head>` at build / SSR time:
+```html
+<head>
+  <title>Notes — Voltro</title>
+  <meta name="description" content="All your notes, in one place." />
+  <meta property="og:title" content="Voltro Notes" />
+  <meta property="og:image" content="/og.svg" />
+  …
+</head>
+```
+### The default document title
+A page's `meta.title` overrides the tab title on navigation. Before any page
+sets one — the initial HTML shell, a route with no `meta`, an error page — the
+browser tab shows the app's **default title**, set in `app.config.ts`:
+```ts
+export default {
+  type: 'web' as const,
+  name:  'AcmeDashboard',   // internal identifier (package/port lookup) — PascalCase by convention
+  title: 'Acme',            // human document title baked into the HTML shell
+}
+```
+`title` is the default `<title>`. It is distinct from `name`, the app's internal
+identifier — leaking that PascalCase identifier into the tab reads as a dev
+artefact. When `title` is unset the shell falls back to `name`, so set a real
+product title on any app users actually see. Per-page `meta.title` still wins
+wherever a page provides one.
+## Dynamic meta from params + loader data + locale
+When the meta depends on the URL or on what the loader fetched, export `meta` as a function. It receives a single object `{ params, loaderData, locale }` and runs at build / SSR time after the loader resolves:
+```tsx
+export const meta = ({ params }: { params: { id: string } }): PageMeta => ({
+  title: `Note ${params.id} — Voltro`,
+  description: '…',
+})
+```
+Reading the loader's result lets the title/description reflect fetched fields — the canonical "page title is the note's title" case:
+```tsx
+export const loader = async ({ params, query }) => ({
+  note: query ? await query('notes.get', { id: params.id }) : undefined,
+})
+export const meta = ({ loaderData }: { loaderData: { note?: { title: string; body: string } } }): PageMeta => ({
+  title:       loaderData.note ? `${loaderData.note.title} — Voltro` : 'Voltro',
+  description: loaderData.note?.body.slice(0, 140) ?? '',
+})
+```
+The third context field — `locale: string` — is the active i18n locale for this render. For `[locale]/…` routes it carries the URL-prefix locale (`'de'` on `/de/notes/42`). For bare-path routes it carries the active locale from the framework's `voltro:lang` cookie when set — so **cookie-based i18n works too** (an authed dashboard with no `[locale]` URL still gets a translated `<title>` that tracks the language switch) — otherwise the app's `defaultLocale`. Use it to localise title / description / canonical / OG per locale at SSG time so search engines see translated head tags on every variant, and to give cookie-i18n pages a translated tab title:
+```tsx
+import { getCatalog } from '../lib/locale'
+import { localeCanonicalUrl } from '../lib/seo'
+export const meta = ({ locale }: { locale: string }): PageMeta => {
+  const c = getCatalog(locale)
+  return {
+    title:       c['seo.notes.title']       as string,
+    description: c['seo.notes.description'] as string,
+    canonical:   localeCanonicalUrl('/notes', locale),
+  }
+}
+```
+`meta(ctx)` runs once per (page × locale) at build time. The full per-locale SSG flow — `[locale]/…` mirror routes, the build-time `<I18nProvider>` wrap, and the dist layout — is documented in [Internationalization → URL strategies](/docs/i18n/url-strategies).
+`loaderData` is the PAGE loader's result. Because `meta` runs server-side after the loader, the SSR'd `<head>` is already correct on first paint — no client-side title patching, no flash.
+## Examples
+### Authenticated dashboard with cookie-driven loader
+```tsx
+// src/pages/dashboard/index.tsx
+import { useLoaderData } from '@voltro/web'
+export const renderMode = 'ssr' as const
+export const loader = async ({ headers }) => {
+  const cookieHeader = headers.cookie ?? ''
+  const me = await fetch(`${INTERNAL_API}/auth/me`, { headers: { cookie: cookieHeader } })
+  if (!me.ok) throw new RedirectError('/login')
+  const user = await me.json()
+  return { user }
+}
+export default function Dashboard() {
+  const { user } = useLoaderData<{ user: User }>()
+  return <h1>Hi {user.name}</h1>
+}
+```
+`RedirectError` is the framework's way to issue a 303 from a loader. See [Navigation](/docs/routing/navigation) for client-side analog.
+### SSG with per-post meta
+`getStaticPaths` has no framework store — it reads its own content source (a CMS client, the filesystem, an API). The loader runs server-side and fetches via `query` (the backend rpc, resolved to its first snapshot):
+```tsx
+// src/pages/blog/[slug].tsx
+import { listPostSlugs, type Post } from '../../content/posts'
+export const renderMode = 'static' as const
+export const getStaticPaths = async () => {
+  const slugs = await listPostSlugs()              // your own content source — fs / CMS / API
+  return slugs.map((slug) => ({ params: { slug } }))
+}
+export const loader = async ({ params, query }) => {
+  // `query` is present only server-side (SSG build / SSR). Resolves the
+  // backend query's first snapshot.
+  return { post: await query!('posts.getBySlug', { slug: params.slug }) }
+}
+export const meta = ({ loaderData }: { loaderData: { post: Post } }): PageMeta => ({
+  title:       `${loaderData.post.title} — Blog`,
+  description: loaderData.post.excerpt,
+})
+```
+## Loaders are NOT React hooks
+They're plain async functions. They can't call `useSubscription`, `useState`, etc. — they run server-side.
+If you need a reactive query (live updates), use `useSubscription` in the component AFTER hydration; for the initial render's data, use the loader.
+## Anti-patterns
+- **Calling `ctx.ai.generate(...)` in a loader without timeouts.** Loaders shouldn't take >2s. For slow data, render a Suspense fallback + `useSubscription` after hydration.
+- **Loaders that mutate state.** Loaders are reads — they're cached, retried, run at build time. Use mutations for writes.
+- **Hardcoding env-only secrets in `meta` tags.** `meta` ships to the client. Public meta only.
+## Where to read next
+- [Navigation](/docs/routing/navigation) — client-side routing, prefetch, Link
+- [Render modes](/docs/routing/render-modes) — which mode means what for loaders
+---
+<!-- source: en/routing/navigation.md -->
+## Navigation
+_Link, useNavigate, prefetch on hover, programmatic redirects, and the external/hash escape hatches._
+Voltro's router is client-side after first paint. Links update the URL via `history.pushState` + re-render the matching page, without a full reload. Loader data prefetches on hover so the next page is ready by the time the user clicks.
+## Typed URLs — the `routes` builder
+`<Link to=…>` does not take a bare string. Its `to` prop is a **branded
+`VoltroUrl`**, minted only by the app's generated `routes` builder or by
+`externalUrl()`. This makes a typo or a link to a route that doesn't exist
+a compile error instead of a dead link at runtime.
+The codegen writes a `routes` builder from your `src/pages/**` tree. Call
+the entry for a pattern with its params to get a typed URL:
+```tsx
+import { Link } from '@voltro/web'
+import { routes } from './.framework/routes'   // generated by `voltro dev`
+<Link to={routes['/notes/[id]']({ id: '42' })}>Open note 42</Link>
+```
+- `routes['/pattern'](params)` → `VoltroRouteUrl`. Missing/extra params are a type error.
+- `withQuery(url, { env: 'prod' })` — append a query string, keeps the brand.
+- `withHash(url, 'section-3')` — append a `#hash`, keeps the brand.
+- `externalUrl('https://example.com')` — the escape hatch for anything the
+  codegen can't model: cross-origin, `mailto:`, `tel:`, hash-only, or a
+  sibling-app route. A deliberate no-op wrapper so any raw string still has
+  to be opted in at the call site.
+```tsx
+import { withQuery, withHash, externalUrl } from '@voltro/web'
+<Link to={withQuery(routes['/notes/[id]']({ id: '42' }), { tab: 'comments' })}>Comments</Link>
+<Link to={withHash(routes['/docs/[[...slug]]']({ slug: ['routing'] }), 'priority')}>Priority</Link>
+<Link to={externalUrl('mailto:hi@x.com')}>Email us</Link>
+```
+## `<Link>`
+```tsx
+import { Link } from '@voltro/web'
+import { routes } from './.framework/routes'
+<Link to={routes['/notes/[id]']({ id: '42' })}>Open note 42</Link>
+```
+What it does:
+- Renders an `<a href="/notes/42">` so the link is a real anchor (SEO, right-click → "Open in new tab", screen readers, etc. all just work).
+- Intercepts plain left-clicks → `history.pushState` + matches the new URL.
+- Modifier keys + middle-click + external URLs pass through to the browser's native behaviour.
+## Prefetch on hover
+```tsx
+<Link to={routes['/notes/[id]']({ id: '42' })} prefetch>Open note 42</Link>
+```
+With `prefetch`, hovering / focusing the link fires the destination's loader in the background. By the time the user actually clicks, `useLoaderData()` resolves immediately on the new page.
+Behaviour:
+- Idempotent — multiple hovers fire one loader call, results are cached.
+- Cached until used or invalidated — a prefetched result stays in the loader cache and is consumed on the next navigation to that route; it isn't discarded on a timer. It's dropped when the route is invalidated (e.g. an error-boundary reset or a mutation that invalidates the loader's data).
+- No effect for `static` pages without loaders (nothing to prefetch).
+For "everything on the page is prefetchable", apps usually wire `prefetch` on every internal link by default. Not much downside — loaders are cheap; the wasted ones are typically empty.
+## `useNavigate`
+For programmatic navigation:
+```tsx
+import { useNavigate } from '@voltro/web'
+const SignOutButton = () => {
+  const navigate = useNavigate()
+  const onSignOut = async () => {
+    await fetch('/auth/signout', { method: 'POST' })
+    navigate('/login')
+  }
+  return <button onClick={onSignOut}>Sign out</button>
+}
+```
+Pass a path string. The router updates `window.location.pathname` + renders the new page.
+## External + hash URLs
+Wrap anything the codegen can't model in `externalUrl()`. `<Link>` detects URLs starting with a scheme (`http://`, `https://`, `mailto:`, `tel:`, `#anchor`) at runtime and falls back to plain browser navigation; a route URL from the `routes` builder does SPA navigation.
+```tsx
+<Link to={externalUrl('https://example.com')}>External</Link>   {/* opens normally */}
+<Link to={externalUrl('mailto:hi@x.com')}>Email</Link>         {/* mailto: handler */}
+<Link to={externalUrl('#section')}>Anchor</Link>              {/* in-page scroll */}
+<Link to={routes['/dashboard']({})}>Internal</Link>            {/* SPA nav */}
+```
+## Active link styling
+```tsx
+import { Link, useLocation } from '@voltro/web'
+const Nav = () => {
+  const pathname = useLocation()
+  return (
+    <ul>
+      <li><Link to={routes['/']({})} className={pathname === '/' ? 'active' : ''}>Home</Link></li>
+      <li><Link to={routes['/about']({})} className={pathname === '/about' ? 'active' : ''}>About</Link></li>
+    </ul>
+  )
+}
+```
+For "active if URL starts with prefix" (parent nav highlighting):
+```tsx
+className={pathname.startsWith('/dashboard') ? 'active' : ''}
+```
+Compose this into your own `NavLink` wrapper with `useLocation()` + `<Link>` when you reuse the pattern across many links.
+## Redirects from a loader
+When the loader detects "user should be elsewhere":
+```ts
+import { RedirectError } from '@voltro/web'
+export const loader = async ({ headers }) => {
+  if (!signedIn(headers)) throw new RedirectError('/login?from=/dashboard')
+  return { /* … */ }
+}
+```
+The framework catches it + emits a 303 with `location: /login?from=/dashboard` on SSR; on a client navigation it runs `navigate(..., { replace: true })` so Back doesn't bounce onto the page that redirected. The default status is 303 (a redirect always lands the browser on a GET of the target); pass `{ status: 307 | 308 }` for a method-preserving redirect. The `redirect()` helper is throwing sugar — `if (!signedIn(headers)) redirect('/login')`.
+For client-side redirects (e.g. after a button click):
+```tsx
+const onSubmit = async () => {
+  await mutate.run({ /* … */ })
+  navigate('/success')
+}
+```
+## Scroll behaviour
+By default, the router scrolls to the top on every push navigation. Override per-link:
+```tsx
+<Link to={withHash(routes['/long-page']({}), 'section-3')}>Jump to section 3</Link>
+```
+Hash links scroll to the matching `id`. Setting `<Link to={routes['/foo']({})} replace>` replaces the history entry (no back-button entry).
+### Back/forward scroll restoration
+The router restores the previous scroll position on **back/forward** navigations. It sets `history.scrollRestoration = 'manual'` and owns restoration itself, saving each entry's scroll offset before you leave it and re-applying it (after the target route paints) when you pop back. This is automatic — no setup. Because the router restores after the loader-gated target paints, the offset lands on the right content even for a page that's still fetching when you click Back.
+Push/replace navigations still scroll to top (or to the hash target); only back/forward restores.
+## Blocking navigation (unsaved changes)
+`useBlocker` holds a pending navigation so you can prompt before the user leaves — the unsaved-changes guard.
+```tsx
+import { useBlocker } from '@voltro/web'
+function EditForm() {
+  const [dirty, setDirty] = useState(false)
+  const blocker = useBlocker(dirty)   // block while the form has unsaved edits
+  return (
+    <form onChange={() => setDirty(true)}>
+      {/* …fields… */}
+      {blocker.blocked && (
+        <div role="dialog">
+          Discard unsaved changes?
+          <button onClick={blocker.retry}>Discard &amp; leave</button>
+          <button onClick={blocker.reset}>Stay</button>
+        </div>
+      )}
+    </form>
+  )
+}
+```
+When `useBlocker`'s argument is `true` (or a predicate returning `true`) and the user tries to leave — a `<Link>` click, an intercepted `<a>`, or an imperative `navigate` — the navigation is **held** and the hook returns `{ blocked: true, to, retry, reset }`:
+- `retry()` — proceed with the held-back navigation.
+- `reset()` — cancel it and stay on the page.
+- `to` — where the user was trying to go (render it in the prompt if you like).
+A full-page unload (tab close, reload, typed URL) additionally triggers the browser's native leave prompt while any blocker is active.
+Pass a **predicate** to allow some destinations:
+```tsx
+// Block everything except an explicit sign-out.
+const blocker = useBlocker(({ to }) => dirty && to !== '/logout')
+```
+## Route announcer (accessibility)
+On a full page load a screen reader announces the new page. A client-side SPA navigation swaps the DOM without that announcement — so the router ships a built-in **route announcer**: a visually-hidden `aria-live` region that speaks the new page's title (from the route's `meta`, falling back to the pathname) on every navigation. This is automatic — no setup, nothing to render. Give each route a `meta.title` and the announcement is meaningful:
+```tsx
+export const meta = () => ({ title: 'Team · Acme' })
+```
+## History APIs
+`navigate` takes a path string only — `(to: string, opts?: { replace?: boolean })`. There is no numeric history overload:
+```ts
+const navigate = useNavigate()
+navigate('/foo')                     // push
+navigate('/foo', { replace: true })  // replace the current entry
+```
+For history traversal, reach for the browser API directly:
+```ts
+window.history.back()      // back
+window.history.forward()   // forward
+```
+## Reading + writing search params
+Read the query string with `useSearchParams()` — a plain `URLSearchParams`. It's SSR-aware (on the server it reads the request URL; on the client, `window.location.search`):
+```tsx
+import { useSearchParams } from '@voltro/web'
+const tab = useSearchParams().get('tab') ?? 'overview'
+```
+Write it with `useSetSearchParams()` — the setter updates the query string on the current pathname (via `navigate`), so the URL changes **and** every reader re-renders immediately:
+```tsx
+import { useSearchParams, useSetSearchParams } from '@voltro/web'
+function Tabs() {
+  const tab = useSearchParams().get('tab') ?? 'overview'
+  const setParams = useSetSearchParams()
+  return (
+    <nav>
+      <button onClick={() => setParams({ tab: 'overview' })}>Overview</button>
+      <button onClick={() => setParams({ tab: 'members' })}>Members</button>
+    </nav>
+  )
+}
+```
+The setter takes either an object / `URLSearchParams`, or an updater that receives the current params:
+```ts
+const setParams = useSetSearchParams()
+setParams({ tab: 'members' })                              // set the whole query
+setParams((p) => { p.set('page', '2'); return p })         // patch one param
+setParams({})                                              // clear the query string
+```
+Search-param writes default to a history **replace** (a filter/tab tweak shouldn't stack a Back entry per keystroke). Pass `{ push: true }` for a distinct history entry, or `{ scroll: false }` to keep the scroll position:
+```ts
+setParams({ page: '2' }, { push: true })
+```
+During SSR there is no history to write — read `useSearchParams()` off the request URL for the first paint and call `useSetSearchParams()` on the client after hydration.
+## Prefetching programmatically
+```tsx
+import { usePrefetch } from '@voltro/web'
+const Card = ({ id }) => {
+  const prefetch = usePrefetch()
+  return (
+    <article onMouseEnter={() => prefetch(`/notes/${id}`)}>
+      {/* …card body, no Link inside */}
+    </article>
+  )
+}
+```
+Useful when the prefetch trigger isn't a `<Link>` (e.g. an entire card area, where the inner link is buried).
+## Anti-patterns
+- **`<a href>` for internal queries.** Falls through the SPA — full reload. Use `<Link>` instead.
+- **`window.location.href = '/foo'`.** Same — full reload. Use `useNavigate()`.
+- **`prefetch` on every link blindly.** For cookie-gated loaders that hit DB, hovering 50 nav items can pile up 50 DB queries. Use `prefetch` for high-confidence destinations only.
+## Where to read next
+- [Loaders & meta](/docs/routing/loaders-and-meta) — what prefetch warms up
+- [Islands](/docs/routing/islands) — for pages where most of the JS is stripped
+---
+<!-- source: en/routing/islands.md -->
+## Islands
+_interactive: 'islands' — ship pure HTML with selectively-hydrated interactive components._
+The **islands** model: serve the page as pure HTML, then hydrate only the bits that need interactivity. The rest of the page is just text + CSS — no React runtime, no JS bundle, no hydration cost.
+Voltro implements islands per-page via the `interactive` export:
+```tsx
+export const renderMode = 'static' as const
+export const interactive = 'islands' as const
+```
+With `interactive: 'islands'`, the framework strips the page's React runtime from the HTML, but loads `*.island.tsx` files as separate chunks + hydrates them in place.
+## When to use islands
+- **Marketing pages** with one interactive widget (a pricing toggle, a code playground).
+- **Docs** that are mostly text but have a search modal + theme toggle.
+- **Blog posts** with an embedded poll or comment widget.
+The split lets you ship near-zero JS for the body + JS only for the islands. Lighthouse scores stay high; React's overhead applies only to the interactive parts.
+## Writing an island
+Wrap a component with `island(Component, { name, hydrate })` and default-export the result. The plain component is NOT enough — without the `island()` call the component is never registered, and at hydration time the runtime logs `island "…" not registered`.
+```tsx
+// src/components/LikeButton.island.tsx
+import { island } from '@voltro/web'
+import { useState } from 'react'
+const LikeButton = ({ initial }: { initial: number }) => {
+  const [count, setCount] = useState(initial)
+  return (
+    <button onClick={() => setCount((n) => n + 1)}>
+      ❤ {count}
+    </button>
+  )
+}
+export default island(LikeButton, { name: 'LikeButton', hydrate: 'visible' })
+```
+- **`name`** — the stable id under which the component is registered. Must be unique within the app. Both the SSR and the client bundle import the file, so the same `island()` call runs on both sides and registers the component in each.
+- **`hydrate`** — when the client runtime should hydrate this island (defaults to `'visible'`). The five strategies are in the table below.
+Use it in a page:
+```tsx
+// src/pages/blog/[slug].tsx
+import LikeButton from '../../components/LikeButton.island'
+export const renderMode = 'static' as const
+export const interactive = 'islands' as const
+export default function Post() {
+  return (
+    <article>
+      <h1>Post title</h1>
+      <p>…body content…</p>
+      <LikeButton initial={42} />
+    </article>
+  )
+}
+```
+What happens at build:
+1. The page is server-rendered to HTML. The `island()` wrapper emits a marker `<div>` carrying the name, props, and hydrate strategy:
+   ```html
+   <div data-voltro-island data-island-name="LikeButton"
+        data-island-hydrate="visible" data-island-props='{"initial":42}'>
+     <button>❤ 42</button>
+   </div>
+   ```
+2. The island bundles into the client chunk.
+3. The client runtime scans for `[data-voltro-island]` markers, looks each name up in its registry, and hydrates that `<div>` per its `data-island-hydrate` strategy.
+The rest of the page stays as inert HTML.
+## Hydrate strategies
+Each island declares WHEN it hydrates via the `hydrate` option (default `'visible'`):
+| Strategy | When the island hydrates | Use for |
+|---|---|---|
+| `load` | Immediately, as soon as the client runtime mounts | Above-the-fold widgets users touch within the first second — search box, primary CTA. |
+| `idle` | When the browser is idle (`requestIdleCallback`, `setTimeout` fallback) | Important widgets that don't need instant interactivity — analytics, secondary nav. |
+| `visible` (default) | When the element scrolls into the viewport (IntersectionObserver) | Anything below the fold — comment box, related-articles carousel. |
+| `interaction` | On the first pointer / keyboard event on the element | Heavy widgets users *might* touch — embedded playground, deep tree viewer. Defers cost until commitment. |
+| `never` | Never — the server-rendered HTML stays inert | Server-only displays that never change after SSR (a build-time status badge). |
+Mix freely inside one page: a `load` search box, a `visible` comment widget, and a `never` build banner can all coexist.
+## Bundle savings
+For a typical Voltro page:
+| Mode | JS shipped |
+|---|---|
+| `interactive: 'full'` | Full React + page bundle (~80-150 KB gzipped) |
+| `interactive: 'islands'` | Island boot loader + island chunks (typically 10-30 KB gzipped) |
+| `interactive: 'none'` | Zero |
+For pages where the body never moves, the savings are dramatic.
+## Island boundaries
+The island component owns its sub-tree's interactivity. Inside an island, you can:
+- `useState`, `useEffect`, every React hook
+- Import + use any other component
+- Render JSX freely
+What you CAN'T do:
+- Make the *parent page* interactive from inside. The island can't trigger a page-level re-render.
+- Read from React Context defined in the page. Each island has its own React root.
+- Share state across islands directly. Use the URL, `localStorage`, or a custom message channel.
+Each island is independent — there is no shared React root across islands. To coordinate, use the URL, `localStorage`, or a custom message channel.
+## Props serialisation
+Props passed to an island must be **JSON-serialisable**. The framework serialises them into the marker's `data-island-props` attribute + hydrates with the same values.
+OK:
+```tsx
+<LikeButton initial={42} kind="heart" tags={['blog']} />
+```
+NOT OK:
+```tsx
+<LikeButton onClick={() => …} />        // functions can't serialise
+<LikeButton date={new Date()} />        // Date → string; use ISO + parse inside
+<LikeButton ref={someRef} />            // refs are component-local
+```
+If you need to pass a function reference, define it INSIDE the island.
+## When NOT to use islands
+- **Whole page is interactive.** Use `interactive: 'full'` — you'd just be adding the island boot overhead for no benefit.
+- **Islands that share state.** Each island is its own root — two islands talking is painful. Coordinate via the URL, `localStorage`, or a message channel.
+- **Islands that hydrate immediately and dominate the page weight.** If the island is the whole page minus a header, just go `interactive: 'full'`.
+## Combining with render modes
+| `renderMode` × `interactive` | Use case |
+|---|---|
+| `static` + `islands` | Marketing landing with a pricing toggle |
+| `static` + `none` | Pure-content blog posts |
+| `static` + `full` | SPA-like docs sites |
+| `ssr` + `islands` | Personalised pages with a few interactive widgets |
+| `isr` + `islands` | High-traffic listings with a "like" button |
+## Inspecting
+The build pipeline reports which chunks are islands:
+```
+[voltro build] vite build…
+  chunks emitted:
+    main.abc.js               145 KB  ← page runtime (full pages only)
+    island-LikeButton.def.js   3.4 KB  ← per-island bundle
+    island-Search.ghi.js       8.1 KB
+```
+Inspect dashboard's "Bundles" panel shows the per-island size + hydration timings.
+## Anti-patterns
+- **Wrapping everything in one big island.** Defeats the purpose — you've just rebuilt full hydration with extra steps.
+- **Passing 100 KB of JSON as island props.** The serialised payload ends up in the HTML — pretty quickly an island's "props" cost dwarfs the saved bundle.
+- **Calling `useLoaderData` inside an island.** Loaders run for the PAGE, not islands. Islands receive props from the page; the page reads loader data.
+## Where to read next
+- [Render modes](/docs/routing/render-modes) — pairs with `interactive`
+- [Navigation](/docs/routing/navigation) — Link + prefetch work the same on islands pages
+---
+<!-- source: en/routing/styling.md -->
+## Styling (Tailwind v4)
+_Tailwind v4 is auto-loaded in every web app's Vite pipeline. The mandatory @source glob, @theme design tokens, and the two silent-failure gotchas (the framework root is .framework/, not src/; a second @theme after @layer is dropped)._
+Every Voltro web app's Vite pipeline auto-loads `@tailwindcss/vite`. Apps that
+don't use Tailwind pay no runtime cost (the plugin emits nothing when no
+`@import "tailwindcss"` appears in any CSS file).
+To use it:
+```css
+/* src/globals.css */
+@import "tailwindcss";
+/* IMPORTANT: the framework's Vite root is `<app>/.framework/`, not
+   `<app>/src/`. Without @source, Tailwind's content scanner misses every .tsx
+   file under src/ — you get an empty `@layer utilities` and zero applied
+   styles. The path is relative to THIS css file. */
+@source "./**/*.{tsx,ts,jsx,js}";
+@theme {
+  --color-background: #0a0a0a;
+  --color-foreground: #fafafa;
+  --radius: 0.5rem;
+}
+```
+```tsx
+// src/pages/layout.tsx
+import '../globals.css'
+```
+Tailwind v4's `@theme` block doubles as the framework's design-tokens surface —
+define your colours / radii / fonts there once and they become available as
+`bg-background`, `text-foreground`, etc. The shadcn convention works directly on
+top: copy a component's source, the classes resolve.
+> **Gotcha:** keep ALL `@theme` blocks ABOVE any `@layer` rules in the same
+> stylesheet. A second `@theme` block placed AFTER `@layer base` is silently
+> dropped by Tailwind v4 — none of its tokens are emitted.
+## Using `@voltro/ui-shadcn` — the kit `@source` is mandatory
+If your app imports `@voltro/ui-shadcn/tokens.css`, you MUST declare a SECOND
+`@source` pointing at the kit's source — otherwise every class that exists ONLY
+inside a kit component (animations like `motion-safe:animate-mesh-drift-a`,
+`motion-safe:animate-twinkle`, kit-internal prose variants) is silently dropped
+from the generated CSS. The components mount and the keyframes register, but the
+`animate-*` utility classes never resolve — no warning is emitted.
+```css
+/* src/globals.css — app uses kit compositions */
+@import "@voltro/ui-shadcn/tokens.css";
+@source "./**/*.{tsx,ts,jsx,js}";
+@source "../node_modules/@voltro/ui-shadcn/src/**/*.{tsx,ts,jsx,js}";
+```
+Why: the kit's `tokens.css` ships its own `@source "./**/*"`, but `@source` paths
+resolve relative to the IMPORTING css file — so once your `globals.css` imports
+the kit, the kit's `./**/*` glob expands to YOUR app's src, not the kit's. The
+kit's own components are then never scanned. Declaring the explicit kit path
+closes the gap — the published package ships its `src/` precisely so this glob
+matches (workspace link and npm install alike).
+How to verify: `curl -sS http://localhost:<port>/@fs/<abs>/src/globals.css | grep
+animate-` should list every kit animation utility you use. If a class is missing,
+the `@source` is misconfigured.