@voltro/cli 0.51.0 → 0.53.0

package/templates/agent-docs/routing.md

@@ -209,36 +209,51 @@ src/pages/[...rest]/page.tsx        # everything else
 
 ## Query strings
 
-Voltro doesn't bake query params into the query — they're orthogonal to the URL pattern:
+Query params are orthogonal to the URL pattern — they never appear in the file path. A page declares its query contract as a **`searchParams` schema export**, the same page-export convention as `meta`, `loader`, and `renderMode`:
 
 ```tsx
-import { useLocation } from '@voltro/web'
+// src/pages/search/page.tsx
+import { Schema } from 'effect'
+import { useSearchParams } from '@voltro/web'
 
-const Page = () => {
-  const pathname = useLocation()
+export const searchParams = Schema.Struct({
+  q:    Schema.optionalWith(Schema.String, { default: () => '' }),
+  page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+})
+
+export default function SearchPage() {
+  const { q, page } = useSearchParams(searchParams)   // q: string · page: number
   // …
-  // 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:
+`useSearchParams(searchParams)` — the page passes its **own** export — returns the decoded, typed shape, SSR-aware: the same call site reads the request URL on the server and `window.location.search` on the client. An invalid query string falls back to the schema's defaults instead of crashing the render, so every field must be optional or carry a default (`Schema.optionalWith(..., { default })` — a schema that cannot decode an empty query throws at the first read, naming the fix). Links to the route type-check against the same schema via [typed `withQuery`](/docs/routing/navigation#typed-withquery).
 
-```tsx
-import { useServerRequest } from '@voltro/web'
+Two boundaries worth knowing:
 
-export const renderMode = 'ssr' as const
+- **`renderMode: 'isr'` + a `searchParams` export is refused at boot** — the isr cache is keyed by path (plus tenant + locale), so the first query's variant would be cached and served for every other query. Use `ssr`, or drop the export and read the query client-side only. See [Render modes](/docs/routing/render-modes#isr-incremental-static-regeneration).
+- **`renderMode: 'static'` build renders see only the schema's defaults** — a build has no query string. The client decodes the live query after hydration; a static page keyed off search params is a client-side concern.
 
-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') ?? ''
-  // …
-}
+### Mirror routes share ONE schema
+
+Bilingual apps with mirrored trees (`pages/x/page.tsx` + `pages/[locale]/x/page.tsx`) re-export the original page's schema instead of copying it:
+
+```tsx
+// src/pages/[locale]/search/page.tsx
+export { searchParams } from '../../search/page'
 ```
 
-Parse the query string explicitly via `useServerRequest()` on the server and `window.location.search` on the client, as shown above.
+One schema, no drift — the mirror page decodes exactly what the original declares.
+
+### Routes without a schema
+
+`useSearchParams()` without an argument stays the raw `URLSearchParams` — nothing changes for a route that declares no schema:
+
+```tsx
+import { useSearchParams } from '@voltro/web'
+
+const q = useSearchParams().get('q') ?? ''
+```
 
 ## Co-locating components, hooks and tests
 
@@ -584,7 +599,7 @@ else — React's render loop still runs to completion in one pass, so a slow
 render is still a slow render. The lever that matters is `defer()`: it puts a
 real `<Suspense>` boundary in the tree, which is what lets the server return to
 the event loop while a slow value is still pending. See
-[Deferring slow data](/docs/routing/loaders-and-meta#deferring-slow-data-defer--await).
+[Deferring slow data](/docs/routing/loaders-and-meta#deferring-slow-data-defer).
 
 Measured against a real server rendering a page with one 400ms deferred field:
 first body byte at 7ms, the deferred chunk at 408ms — and a probe firing every
@@ -599,8 +614,11 @@ Two consequences worth knowing:
   framework hands the URL to React instead, so it goes out `async` at the end
   of the shell and hydration starts immediately.
 - **`isr` and `static` are still buffered**, because both produce a stored
-  artefact rather than a response. That is also why `defer()` is an error on
-  those modes.
+  artefact rather than a response. `defer()` is an error on those modes —
+  with ONE exception: an isr page that exports `ppr = true` (partial
+  prerendering, below) caches the shell and appends its deferred holes per
+  request. On `static` it stays an error even with `ppr` — a static file is
+  served by any dumb file host, which cannot append anything.
 
 Apps do not call the renderer directly. If you are building your own server on
 top of `@voltro/web/ssr`, `renderPageToStream` is the entry point — it takes the
@@ -637,6 +655,88 @@ Cache backends:
 - `memory` *(default)* — in-process, doesn't survive restarts.
 - `postgres` — `SSR_CACHE=postgres`. Survives restarts, shared across api instances.
 
+An `isr` page that also declares a [`searchParams` schema](/docs/routing/pages#query-strings) is refused at boot — the cache is keyed by path (plus tenant + locale), not by query, so the first query's variant would be served for every other query; use `ssr`, or drop the export and read the query client-side only.
+
+### isr renders are anonymous
+
+An `isr` render is a **shared** render: the HTML it produces is cached and served
+to every visitor inside the revalidate window. The framework therefore strips
+credential material before the render runs — the cookie jar (except the
+`voltro:locale` cookie), the `authorization` header, and every `x-voltro-*`
+header never reach an isr page's loaders, `ctx.query`, or `useServerRequest()`.
+`x-tenant` and `accept-language` survive, because the cache key (tenant + locale)
+is derived from them.
+
+Concretely: a loader on an isr page that reads subject-scoped data gets the
+**anonymous** answer — the same one every visitor will see — instead of caching
+the first visitor's data for everyone. This applies identically under
+`voltro dev` and `voltro start`, so a page cannot look personalised in dev and
+silently serve shared HTML in production. A page whose loader needs the signed-in
+subject belongs on `renderMode: 'ssr'`.
+
+## Partial prerendering (ppr) — cached shell + per-request holes
+
+An isr page can combine a **cached, anonymous shell** with **per-request
+dynamic holes**: the shell comes straight out of the cache (or the miss
+render), and the deferred fields stream in behind it on the SAME response —
+personalised, never cached.
+
+```tsx
+export const renderMode = 'isr' as const
+export const revalidate = 60
+export const ppr = true
+
+export const loader = ({ headers }) => defer(
+  { title: 'Dashboard' },                    // SHELL — cached, anonymous
+  { greeting: personalGreeting(headers) },   // HOLE — per request, never cached
+)
+```
+
+How it works, and what each half may do:
+
+- **The shell render is fail-closed, not merely stripped.** Its loader context
+  and `useServerRequest()` snapshot THROW by name when a credential is read
+  (`cookie`, `authorization`, `x-voltro-*` headers; any cookie but
+  `voltro:locale`): the first request answers with an error naming the read
+  and the fix, instead of baking silently-empty subject data into an artefact
+  served to everyone. `x-tenant` and `accept-language` stay readable — they
+  are cache-key inputs.
+- **A hole is an `async` function.** Its credential reads happen inside the
+  promise: on the shell pass they reject harmlessly into the `<Await>`
+  fallback; on the per-request hole pass they see the real request. A
+  credential read in the EAGER half (or synchronously while building the
+  hole promise) is the named error above — that is the fail-closed contract.
+- **Holes reveal through hydration.** The shell carries the `<Await>`
+  fallbacks, the registry bootstrap and the deferred-id payload; each hole
+  value is appended as an inline settle script the moment its promise
+  resolves, and the hydrated `<Await>` renders it. `ppr` therefore requires
+  `interactive: 'full'` — `'none'` ships no JS to reveal anything and
+  `'islands'` never hydrates the page root; both are refused by name.
+- **The eager half runs twice per request** (shell render on a cache miss,
+  hole pass always). That is the cost model on purpose: eager data is the
+  cheap, cacheable half; per-subject work belongs in the holes.
+- **Client-side navigation** to a ppr page runs the loader in the browser —
+  holes resolve through the client defer path, same `<Await>` markup.
+- **Invalidation is the shell's**: `revalidate`, `cacheInvalidatesOn` and
+  on-demand revalidation purge the SHELL entry; holes are never cached, so
+  there is nothing to invalidate.
+- **Layout loaders cannot defer on a ppr page** (v1): holes live in the page
+  loader; a deferring layout is refused by name.
+- **CSP nonces are refused on ppr exactly as on isr** — the cached shell
+  carries inline registry scripts that cannot be per-request-nonce'd. Use
+  `renderMode: 'ssr'` for nonce'd pages, or a hash-based policy.
+- **Without JavaScript** (a text crawler, JS disabled) the hole fallbacks
+  stay visible — the shell is complete, correct HTML; only the holes remain
+  in their pending state. There is deliberately NO "buffer fully for
+  crawlers" mode: user-agent sniffing serves different documents to crawlers
+  and users, which is the cloaking failure class.
+- **A client that disconnects mid-response** simply stops receiving settle
+  scripts; nothing corrupts, the loader's own work completes server-side.
+
+The response carries `x-voltro-ppr: shell+holes` next to the usual
+`x-voltro-cache` headers, and the server counts shell serves, hole passes and
+hole latency (see [Observability](/docs/observability/overview)).
+
 ## Tenant-aware ISR
 
 For multi-tenant ISR (each tenant gets its own cache entry):
@@ -662,6 +762,63 @@ The framework reads Postgres logical replication; writes to `posts` or `comments
 
 Requires `SSR_CACHE=postgres` and a `wal_level=logical` Postgres.
 
+## On-demand revalidation
+
+The third invalidation axis, next to time (`revalidate`) and CDC
+(`cacheInvalidatesOn`): server code in the api process drops ISR cache entries
+imperatively, on **every** web replica — including on dialects that have no
+CDC at all (sqlite, mysql, memory), which is the case this exists for.
+
+```ts
+import { revalidatePath, revalidateTable, revalidateTag } from '@voltro/runtime'
+
+// inside a mutation / action / webhook receiver / REST route handler:
+await revalidateTable('posts')          // drop every route whose cacheInvalidatesOn lists 'posts'
+await revalidatePath('/blog/[slug]')    // drop every cached instance of the route
+await revalidatePath('/pricing')        // drop one concrete path (all tenant+locale variants)
+await revalidatePath('/pricing', { tenant: 'acme' })  // …one tenant's variants only
+await revalidateTag('pricing')          // drop every route whose cacheInvalidatesOn lists the tag
+```
+
+**Tags are tables that never were one.** `cacheInvalidatesOn` accepts free
+strings, so one mechanism covers both: declare `cacheInvalidatesOn:
+['posts', 'pricing']` on any number of routes and `revalidateTag('pricing')`
+drops them all — the `revalidateTag` thinking Next.js users bring works
+unchanged.
+
+**How it travels.** The api process publishes; every `voltro start` replica
+subscribes. Two transports, either or both:
+
+- **postgres**: a `pg_notify` on the same LISTEN connection the CDC
+  invalidator already holds — a postgres deployment needs **no broker**.
+- **a broker**: set `BROADCAST_URL` (`redis://` or `nats://`) on **both** the
+  api and the web deployment. This is the path for non-postgres dialects. On
+  a broker shared by several projects, also set `VOLTRO_BROADCAST_NAMESPACE`
+  on both sides — the channel is namespaced by that variable (the api's and
+  the web app's names differ, so a name-derived namespace can't pair them).
+
+A web process with ISR routes and **neither** transport warns at boot
+(`NO revalidation transport`) — calls then change nothing and cached pages
+live out their own `revalidate` window. Under `voltro dev` there is no ISR
+cache; the calls are debug-logged no-ops.
+
+Three edges, all deliberate:
+
+- **Only `isr` routes.** `revalidatePath` against a `static` route logs a
+  named error on the web process — static HTML is a build artifact `voltro
+  start` never re-renders; rebuild to change it. (The transport is
+  fire-and-forget, so the error surfaces in the web replica's log, not at the
+  call site.)
+- **Purge-during-render is guarded.** A background SWR refresh (or miss fill)
+  that started before the purge landed is discarded instead of writing the
+  pre-purge page back with a full TTL — a per-key generation counter, on both
+  cache backends.
+- **On postgres you don't need this for the plain publish case** — a route
+  declaring `cacheInvalidatesOn: ['<table>']` is already dropped by CDC when
+  the table changes. Reach for the imperative API for non-postgres dialects,
+  pattern purges of routes whose loaders read data indirectly, and tag
+  fanout.
+
 ## spa (client-only, with an optional SSR layout shell)
 
 ```tsx
@@ -1383,6 +1540,55 @@ They're plain async functions. They can't call `useSubscription`, `useState`, et
 
 If you need a reactive query (live updates), use `useSubscription` in the component AFTER hydration; for the initial render's data, use the loader.
 
+## OG images from a template — `ogImage`
+
+Declare the page's `og:image` as a satori JSX template and the framework
+produces the PNG: at BUILD time for `static` pages (hashed into
+`dist/assets/og/`, tags injected with the absolute `seo.siteUrl`), ON DEMAND
+for `ssr` pages over a signed route with a cache.
+
+```tsx
+export const ogImage = ({ params, loaderData, locale }: {
+  params: Record<string, string>
+  loaderData: unknown
+  locale: string
+}) => ({
+  type: 'div',
+  props: {
+    style: {
+      display: 'flex', width: '100%', height: '100%',
+      background: '#0b1220', color: '#fff', fontSize: 72, fontFamily: 'Inter',
+      alignItems: 'center', justifyContent: 'center',
+    },
+    children: `My post ${params['slug'] ?? ''} (${locale})`,
+  },
+})
+```
+
+`meta` wiring is automatic: `og:image`, `twitter:image` and `twitter:card`
+land in the head — unless your `meta` already sets `og:image`, which then
+wins (no duplicate tag for crawlers to pick at random).
+
+**Preconditions, decided rather than improvised:**
+
+- **A declared font is REQUIRED** ([Fonts](/docs/routing/fonts)) — satori
+  cannot render text without a font buffer, and there is no bundled default
+  (that would ship a license artifact). Missing font → a named build/boot
+  error with the fix. The renderer uses the ORIGINAL un-subsetted files, so
+  glyphs outside your declared subsets still render.
+- **`ssr` pages need `VOLTRO_OG_SECRET` in multi-replica deploys.** The
+  render signs the on-demand URL (HMAC over route + params + tenant +
+  locale; tampering answers 403) and a per-boot minted secret only verifies
+  in the process that signed it — behind a load balancer set the env var
+  (same value on every replica), or the deploy boot refuses, loudly. Images
+  are cached in the same backend as the page cache; tenant and locale are
+  part of the key wherever the template uses them.
+- **Emoji are not supported** — satori renders them only via a per-glyph CDN
+  fetch, which collides with the no-external-requests posture. Use an image
+  in the template instead: a `?image` import's `blurDataURL`/`src`, or any
+  data-URI (`src: \`data:image/png;base64,…\``) inside an `img` element of
+  the template — the standard avatar/logo card works that way.
+
 ## 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.
@@ -1423,7 +1629,7 @@ import { routes } from './.framework/routes'   // generated by `voltro dev`
 ```
 
 - `routes['/pattern'](params)` → `VoltroRouteUrl`. Missing/extra params are a type error.
-- `withQuery(url, { env: 'prod' })` — append a query string, keeps the brand.
+- `withQuery(url, { env: 'prod' })` — append a query string, keeps the brand. On a route whose page declares a `searchParams` schema, the params type-check against it (below).
 - `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
@@ -1438,6 +1644,28 @@ import { withQuery, withHash, externalUrl } from '@voltro/web'
 <Link to={externalUrl('mailto:hi@x.com')}>Email us</Link>
 ```
 
+### Typed `withQuery`
+
+For a route whose page exports a [`searchParams` schema](/docs/routing/pages#query-strings),
+the generated builder brands the URL with the schema's decoded shape — through a
+**type-only** import, so no page module enters the routes file's value graph and
+code-splitting stays intact. `withQuery` then type-checks the params against the
+page's contract: a misspelt key or a wrong value type is a compile error.
+
+```tsx
+<Link to={withQuery(routes['/notes'](), { page: 2 })}>Page 2</Link>
+// withQuery(routes['/notes'](), { pgae: 2 })    → compile error (unknown key)
+// withQuery(routes['/notes'](), { page: 'x' })  → compile error (wrong type)
+```
+
+The encode is canonical and schema-free: strings pass through, numbers and
+booleans via `String()`, arrays become repeated keys (`?tag=a&tag=b`), and
+`undefined` params are omitted. A `Date` (or any object) is refused loudly —
+there is no canonical URL form the type layer could guarantee; declare the field
+as a string/number transform in the page's `searchParams` schema and pass that
+instead. Routes of `siblingApps` stay untyped — their pages live in another
+app's compile graph.
+
 ## `<Link>`
 
 ```tsx
@@ -1563,6 +1791,59 @@ The router restores the previous scroll position on **back/forward** navigations
 
 Push/replace navigations still scroll to top (or to the hash target); only back/forward restores.
 
+## View transitions
+
+Opt in to the browser's [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) for SPA navigations — the browser cross-fades the old and new page (and lets you animate individual elements) with zero animation library:
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'MyApp',
+  router: {
+    viewTransitions: true,
+  },
+}
+```
+
+With the flag on, every route swap — `<Link>` clicks, `navigate(...)`, back/forward — runs through `document.startViewTransition`. Individual navigations override the default in either direction:
+
+```tsx
+navigate('/reports', { transition: false })   // this one swaps plainly
+<Link to={routes['/photos/[id]']({ id })} transition>Open</Link>  // this one transitions even when the app default is off
+```
+
+**Fallback is exact.** In a browser without the API, and for users with `prefers-reduced-motion: reduce`, navigation behaves precisely as without the flag — same timing, no animation, nothing to feature-detect yourself.
+
+**Styling is plain CSS, not a framework DSL.** The default is a full-page cross-fade. To animate a specific element independently (the classic shared-element move), give it a `view-transition-name` and style the browser's pseudo-elements:
+
+```css
+.post-cover { view-transition-name: post-cover; }
+
+/* Tune the root cross-fade */
+::view-transition-old(root) { animation-duration: 150ms; }
+::view-transition-new(root) { animation-duration: 150ms; }
+
+/* The named element morphs between its old and new position */
+::view-transition-group(post-cover) { animation-duration: 300ms; }
+```
+
+An element that keeps its `view-transition-name` across both pages is morphed from its old to its new position automatically — that is the whole shared-element recipe.
+
+Three behaviors worth knowing, all deliberate:
+
+- **`defer()` fields resolve outside the transition.** The transition animates to the committed page — with a deferred field still showing its fallback. The field's later resolution is an ordinary React update, not a second animation. Same rule for an explicit `Pending` skeleton: the swap **to** the skeleton is the transition; the settled content arrives un-animated.
+- **Rapid navigation skips, never queues.** Navigating again while a transition is animating skips the running one (per the API's spec) and the last navigation wins — no queue, no dead time.
+- **Overlays and modals do not transition.** A view transition snapshots the whole viewport, so running one on an overlay opening would cross-fade the entire page for a change that visually touches one layer. Router view transitions therefore apply to **route navigations only**; overlay/dialog state changes never trigger one.
+
+**Static / multi-page documents:** a full-document navigation (between `renderMode: 'static'` pages, or any MPA link) never goes through the SPA router — opt those into the browser's cross-document transitions with CSS alone, no framework involvement:
+
+```css
+@view-transition { navigation: auto; }
+```
+
+**Coming from Astro?** There is no `transition:persist` equivalent because none is needed — persistent state lives in a [layout](/docs/routing/layouts), and layouts stay mounted across SPA navigations natively.
+
 ## Blocking navigation (unsaved changes)
 
 `useBlocker` holds a pending navigation so you can prompt before the user leaves — the unsaved-changes guard.
@@ -1631,7 +1912,37 @@ 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`):
+The recommended way to read the query string is **typed**: declare the page's
+query contract as a `searchParams` schema export and pass that same export to
+`useSearchParams(...)`:
+
+```tsx
+import { Schema } from 'effect'
+import { useSearchParams } from '@voltro/web'
+
+export const searchParams = Schema.Struct({
+  tab:  Schema.optionalWith(Schema.String, { default: () => 'overview' }),
+  page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+  tags: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+})
+
+export default function Notes() {
+  const { tab, page, tags } = useSearchParams(searchParams)
+  // tab: string · page: number · tags: readonly string[]
+}
+```
+
+- **SSR-aware** — the same call site decodes the request URL on the server and `window.location.search` on the client.
+- **Total** — an invalid query string is never a crash or a 500: the decode falls back to the schema's defaults, exactly like visiting without a query.
+- **Every field must be optional or carry a default** (`Schema.optionalWith(..., { default })`). A schema that cannot decode an empty query throws at the first read, naming the fix — that is a definition error, not a runtime input problem.
+- **Array fields keep their shape** — `?tag=a&tag=b` decodes to `['a', 'b']`, and a single `?tag=a` decodes to `['a']`, not a bare string.
+
+The same schema types links to the route — see [typed `withQuery`](#typed-withquery)
+above — and the page-export convention itself is documented in
+[Pages → Query strings](/docs/routing/pages#query-strings).
+
+`useSearchParams()` **without** an argument stays the raw `URLSearchParams` —
+the fallback for routes that declare no schema:
 
 ```tsx
 import { useSearchParams } from '@voltro/web'
@@ -1639,7 +1950,7 @@ 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:
+Write the query 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'
@@ -1673,6 +1984,32 @@ 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.
 
+### Typed writes
+
+Pass the page's `searchParams` schema to get the **typed** setter. Its object form REPLACES the query — same semantics as the untyped form; a field you leave out decodes to its default on the next read. Its updater form receives the **current decoded params**, so a merge is one explicit spread — the pagination flip that keeps `?filter` stops being a hand-rolled merge:
+
+```tsx
+import { useSetSearchParams } from '@voltro/web'
+import { searchParams } from './page'
+
+const setParams = useSetSearchParams(searchParams)
+setParams({ page: 2 })                          // replaces → ?page=2 (filter dropped)
+setParams((p) => ({ ...p, page: p.page + 1 }))  // keeps ?filter — typed merge
+```
+
+A misspelt key or wrong value type in the object form is a compile error; in the updater, the typed `p` is the guard (`p.pgae` does not compile).
+
+For a plain `<Link>` that keeps the current query, compose the two primitives you already have — decode the current params, spread them into `withQuery`:
+
+```tsx
+const current = useSearchParams(searchParams)
+<Link to={withQuery(routes['/search'](), { ...current, page: current.page + 1 })}>Next</Link>
+```
+
+That composition is also the whole story on **retaining params across navigations**: there is no implicit retain list — a param survives a navigation only if the link (or setter) encodes it, which keeps every URL self-describing. Spread what must survive; everything else resets to its schema default.
+
+**Layout-level schemas are deliberately not a layer of their own:** the schema is a page export. A layout (or any co-located component) that needs the same params imports the page's schema and calls `useSearchParams(searchParams)` with it — composition per schema import, one schema, no drift.
+
 ## Prefetching programmatically
 
 ```tsx
@@ -1719,15 +2056,13 @@ export const renderMode = 'static' as const
 export const interactive = 'islands' as const
 ```
 
-> **Islands cut hydration WORK, not DOWNLOAD — read this before you pick the mode.**
->
-> `interactive: 'islands'` ships **exactly the same JavaScript** as `interactive: 'full'`. Measured on the framework's reference fixture, the same page: `full` = 195,229 bytes gzipped of first-load JS, `islands` = 195,231 bytes. That is the whole difference — two bytes of noise.
+> **Islands cut hydration WORK and DOWNLOAD — the page ships its own lean entry.**
 >
-> The reason is structural, not a missing optimisation pass: the generated browser entry imports `mount` and your `App` at value level, so the browser has already downloaded, parsed and evaluated the entire app bundle before the islands branch is even reached. Only `interactive: 'none'` removes bytes today — it strips every `<script type="module">` and `<link rel="modulepreload">` from the page's HTML.
->
-> So islands are the right choice when the cost you want back is **CPU on the main thread** (hydration walking a large tree, effects firing across a page of prose). They are the wrong choice if you adopted them to make the download smaller — for that, use `interactive: 'none'` and put the interactive bits behind a separate page, or accept the full payload.
+> `voltro build` emits a dedicated browser entry per `interactive: 'islands'` page: react + the island runtime + exactly that page's islands — not the router, not the Effect runtime, not the subscription cache, not the app shell. Measured on the framework's reference fixture (pinned in `packages/web/bundle-budget.json`, as of 2026-08-25): an islands page is **59.6 KB gzipped first-load** vs **181.9 KB gzipped** for the same page as `full` — a factor of ~3. The bundle-budget test additionally pins a hard <70 KB bound AND the ratio (<50 % of the full page). `interactive: 'none'` stays at 0 B.
+
+With `interactive: 'islands'`, the page's HTML is server-rendered and its script tag points at the page's own entry. That entry registers the page's islands, scans for island markers, and hydrates each one on its own schedule — the page component itself never runs in the browser.
 
-With `interactive: 'islands'`, the page's HTML keeps its script tags and the app bundle still loads; what changes is that `mount()` skips hydrating the page tree and instead scans for island markers, hydrating each one on its own schedule.
+Looking for Astro's **"Server Islands"** — per-request-rendered holes in otherwise static pages? In Voltro that is planned as **partial prerendering (PPR)**, not part of islands mode.
 
 ## When to use islands
 
@@ -1735,15 +2070,19 @@ With `interactive: 'islands'`, the page's HTML keeps its script tags and the app
 - **Docs** that are mostly text but have a search modal + theme toggle.
 - **Blog posts** with an embedded poll or comment widget.
 
-In each case what you get back is hydration time, not bytes: React's *runtime* overhead applies only to the interactive parts, while the *download* is unchanged. If the page has no interactive part at all, `interactive: 'none'` is strictly better — it ships no JavaScript.
+In each case you get back both halves: hydration work runs only inside the islands, and the download shrinks to react + the island runtime + those islands. If the page has no interactive part at all, `interactive: 'none'` is strictly better — it ships no JavaScript.
+
+`interactive: 'none'` does not take forms with it. The strip removes every module script and modulepreload, but leaves `<form>` markup — and the form-flash JSON script (`#__voltro_form_flash__`, inert JSON, not executable code) — in place. An `<AutoForm>` on an `interactive: 'none'` page is therefore fully usable without a single byte of JavaScript: it renders `action="/form/<mutationTag>"` + `method="post"` and submits as a native form POST. Details: [Forms without JavaScript](/docs/ui/forms-and-tables).
 
 ## 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`.
 
+`island` comes from the react-only subpath **`@voltro/web/islands`** (only react + react-dom/client in its graph). Importing the `@voltro/web` barrel inside an island file is a BUILD ERROR — see the import rules below.
+
 ```tsx
 // src/components/LikeButton.island.tsx
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 import { useState } from 'react'
 
 const LikeButton = ({ initial }: { initial: number }) => {
@@ -1759,7 +2098,7 @@ 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.
+- **`hydrate`** — when the client runtime should hydrate this island (defaults to `'visible'`). The six strategies are in the table below.
 
 Use it in a page:
 
@@ -1790,8 +2129,8 @@ What happens at build:
      <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.
+2. The island compiles into the page's own browser entry — react + the island runtime + this page's islands (see [How the per-page entry works](#how-the-per-page-entry-works)).
+3. That entry 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.
 
@@ -1805,33 +2144,57 @@ Each island declares WHEN it hydrates via the `hydrate` option (default `'visibl
 | `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. |
+| `only` | Client-only: the server renders an empty placeholder, the client mounts fresh with `createRoot` instead of hydrating | Components that touch `window` during render — chart/map libraries. |
 | `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.
 
 ## What each mode actually costs
 
-Measured on the framework's reference web fixture — the same page, three values of `interactive`, first-load JavaScript read out of the page's own built HTML (entry script + every `modulepreload`) and gzipped:
+Measured on the framework's reference web fixture (pinned in `packages/web/bundle-budget.json`, as of 2026-08-25) — the same page, three values of `interactive`, first-load JavaScript read out of the page's own built HTML (entry script + every `modulepreload`) and gzipped:
 
 | Mode | JS shipped | Hydration |
 |---|---|---|
-| `interactive: 'full'` | 195,229 B gz | The whole page tree |
-| `interactive: 'islands'` | 195,231 B gz | Only the marked islands, each on its own strategy |
+| `interactive: 'full'` | ≈181.9 KB gz — the app entry: router, Effect runtime, subscription cache, app shell | The whole page tree |
+| `interactive: 'islands'` | ≈59.6 KB gz — a per-page entry: react + the island runtime + this page's islands | Only the marked islands, each on its own strategy |
 | `interactive: 'none'` | 0 B — every module script and modulepreload is stripped from the HTML | None |
 
-Two things to take from that table. **`islands` is not a download optimisation** — it is level with `full` to within two bytes, and the numbers above are the whole story, not a "before we finish the work" snapshot. And **`none` is the one that removes bytes**, because it is the only mode that removes the script tags.
+Two things to take from that table. **`islands` IS a download optimisation now** — an islands page ships roughly a third of the full page's first-load JS, because its entry carries no router, no Effect runtime, no subscription cache and no app shell. And **`none` remains the floor**: it is the only mode that removes the script tags entirely.
 
-The floor those first two numbers sit on is the framework's browser runtime — React plus the Effect-based RPC client — and it is pinned in CI so it cannot drift silently. Reproduce it yourself:
+Both islands numbers are pinned in CI — the hard <70 KB bound and the <50 %-of-full ratio — so the gap cannot drift shut silently. Reproduce it yourself:
 
 ```sh
 node packages/web/scripts/bundle-budget.mjs
 ```
 
-## Making islands reduce bytes too
+## How the per-page entry works
+
+`voltro build` emits one browser entry per `interactive: 'islands'` page. The build finds the page's islands by walking the page's **relative import graph** for `*.island.tsx` files — transitively, through intermediate components. Only what is reachable from an island file ships; the page component itself may import anything, because on an islands page it never runs in the browser.
+
+Two rules to know:
 
-It is a real gap, and it is a build-pipeline change rather than a runtime one: the browser entry would have to be emitted *per page*, so an islands page's entry imports the island runtime and its own islands instead of the whole app. Nothing in the page's own code can shortcut it — the bytes are pulled in above `mount()`, by the entry that imports it.
+- **`interactive` must be a source LITERAL.** `export const interactive = 'islands' as const` selects the lean entry; a computed value does not — the page then ships the full entry as before, and the build says so loudly.
+- **It applies on all three paths.** `voltro build` (SSG), `voltro start` (ssr/isr islands pages) and `voltro dev` (the same entry mechanism, on demand) — including the import-rule violations below, which fire in dev already, not first in the build.
 
-Until then, if download size is what you are optimising, reach for `interactive: 'none'`.
+### What an island may import (build errors, not runtime crashes)
+
+An island file — or anything in its relative import graph — must NOT import:
+
+- `@voltro/web` (the barrel — router hooks, `<Link>`)
+- `@voltro/i18n` (`useT`)
+
+An island hydrates provider-less in its own root, so these hooks would throw there — and the barrel would additionally drag the Effect runtime into the lean entry. The build error names the file and the specifier.
+
+Allowed: `@voltro/web/islands`, react, relative browser-safe imports — and `@voltro/client` / `@voltro/ui` (both count as framework usage and trigger the client boot below).
+
+### Framework islands: `useSubscription` and friends
+
+An `@voltro/client` import in the island graph is DETECTED — that page's entry then boots the rpc client (a `VoltroRuntimeProvider` around each island root), and the island receives live data. Pages whose islands are purely presentational never pay the client core.
+
+### Limits
+
+- An islands page reached via **SPA navigation** from a full page runs inside the already-loaded app bundle — the saving applies to the first visit / hard load of the islands page.
+- All islands of one page **share one entry** (no per-island lazy chunk) — the hydrate strategies control WHEN an island hydrates, not when it loads.
 
 ## Island boundaries
 
@@ -1851,7 +2214,7 @@ Each island is independent — there is no shared React root across islands. To
 
 ## 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.
+Island props cross the boundary **as JSON in an HTML attribute**. The framework serialises them into the marker's `data-island-props` attribute + hydrates with the same values. `Date` arrives as an ISO string, `Map`/`Set` as `{}`, and functions are lost — in dev the framework warns, naming the island and the prop. Pass JSON shapes and reconstruct richer types inside the island.
 
 OK:
 
@@ -1887,13 +2250,13 @@ If you need to pass a function reference, define it INSIDE the island.
 
 ## Inspecting
 
-Each `*.island.tsx` becomes its own chunk, so `.framework/dist/assets/` carries an `island-<Name>-<hash>.js` per island alongside the app chunks. Listing that directory is the whole report:
+Each islands page gets its own lean entry in `.framework/dist/assets/`, alongside the app entry that full pages share. Listing that directory is the whole report:
 
 ```sh
 ls -l .framework/dist/assets
 ```
 
-Per-island chunks are cached independently across deploys and fetched in parallel — but note they are *additional* files reachable from the app bundle, not a replacement for it. See the mode table above for what actually reaches the browser.
+All islands of one page share that page's entry — there is no per-island lazy chunk. See the mode table above for what actually reaches the browser.
 
 ## Anti-patterns
 
@@ -1982,14 +2345,312 @@ the `@source` is misconfigured.
 
 
 
+---
+
+<!-- source: en/routing/assets.md -->
+## Images & static assets
+
+_The build-time image pipeline — ?image imports become srcSet variants (AVIF/WebP + fallback) with inferred dimensions and a blur placeholder; the <Image> primitive, the CDN loader seam, and the sharp setup._
+
+`<Image>` is the responsive image primitive; the `?image` import suffix is the
+build-time pipeline behind it. Together they replace next/image: variants and
+placeholders are produced at build time for static assets, on demand in dev.
+
+## The pipeline: `?image` imports
+
+```tsx
+import { Image } from '@voltro/web'
+import hero from '../assets/hero.jpg?image'
+
+export default function Page(): React.ReactElement {
+  return <Image src={hero} alt="Team photo" priority />
+}
+```
+
+The `?image` suffix turns the import into an optimized asset object instead of
+a URL string: the build encodes every ladder width up to the intrinsic width
+(640 … 3840, capped) as AVIF + WebP plus a same-family fallback (jpeg/png),
+hashes the variants into `dist/assets/`, reads the intrinsic `width`/`height`,
+and inlines a 16px blur placeholder as a data URI. `<Image>` renders it as a
+`<picture>` with one `<source>` per modern format; dimensions and blur are
+inferred — the CLS-required `width`/`height` props stop being hand-written for
+imported assets, and `placeholder="blur"` is the default (opt out with
+`placeholder="empty"`).
+
+The suffix is an explicit opt-in **on purpose**: a bare image import keeps
+Vite's plain hashed-URL semantics, so existing `<img src={imported}>` and CSS
+references are untouched.
+
+Add the ambient type once per app (`src/voltro-image.d.ts`):
+
+```ts
+declare module '*?image' {
+  const asset: {
+    readonly src: string
+    readonly width: number
+    readonly height: number
+    readonly blurDataURL: string
+    readonly srcSet: string
+    readonly sources: ReadonlyArray<{ readonly type: string; readonly srcSet: string }>
+  }
+  export default asset
+}
+```
+
+## Dev vs build vs start
+
+- **`voltro build`** encodes variants into `dist/assets/` under content
+  hashes. The transforms run through a persistent cache
+  (`.framework/image-cache/`), so the second build re-encodes nothing — 500
+  posts × 8 widths × 2 formats is a one-time cost.
+- **`voltro dev`** serves transforms on demand from
+  `/_voltro/image/<assetId>` (same cache). The endpoint answers ONLY for
+  assets registered by an actual `?image` import — a free path parameter
+  would be a dev file-read surface.
+- **`voltro start`** serves build artifacts only. There is deliberately no
+  production transform endpoint — no transform-DoS surface. This is a
+  documented dev/prod divergence.
+
+## Configuration
+
+```ts
+// app.config.ts (web)
+export default {
+  type: 'web' as const,
+  name: 'MyApp',
+  images: {
+    formats: ['avif', 'webp'],  // modern formats, in <source> order (default)
+    quality: 75,                // encode quality for every variant (default)
+  },
+}
+```
+
+## sharp — the native encoder
+
+The pipeline runs on [sharp](https://sharp.pixelplumbing.com), shipped as an
+**optional dependency of @voltro/cli** — auto-available in every project,
+nothing to install. sharp ≥0.33 ships prebuilt binaries as `@img/*` platform
+packages with no install script, so pnpm 10's build-script approval gate does
+not apply.
+
+If your installer **omits optional dependencies**, the platform prebuilds are
+dropped: sharp resolves but throws on load. The pipeline then serves original
+images with ONE loud warning naming the fix (`pnpm add -D sharp`, or reinstall
+without omitting optional deps), and `voltro doctor` distinguishes
+"not installed" from "installed but binary missing". Never a silent
+passthrough.
+
+## Limits (and the answer for each)
+
+- **Dynamic `src`** — a URL from `loaderData` or CMS frontmatter cannot be
+  seen at build time. Use the loader seam: `<Image src={url} loader={cdn}>`
+  against your image CDN or the storage plugin's public-serve endpoint (which
+  resizes on the fly). The `quality` prop flows into the loader for exactly
+  this path; for `?image` assets quality is baked at build time from
+  `images.quality`.
+- **Remote images** — same: loader seam, not the build pipeline.
+- **Markdown-content images** (a blog's relative references) — copied +
+  hashed by the content pipeline; build-time transformation for those is a
+  named non-goal for now.
+
+## `<Image>` without the pipeline
+
+Everything from before still holds for plain string `src`: lazy loading +
+async decode by default, `priority` for the LCP image, required
+`width`/`height` (or `fill`) for CLS, `sizes`, and the pluggable
+`ImageLoader`/`ImageConfigProvider` seam. See the reference for the full prop
+table.
+
+
+
+---
+
+<!-- source: en/routing/third-party-scripts.md -->
+## Third-party scripts
+
+_The <Script> component — declared loading strategies (afterInteractive, lazyOnload), process-wide dedupe, remount-safe onLoad, behavior per interactive mode, and the CSP story for client-injected tags._
+
+`<Script>` loads third-party scripts declaratively instead of hand-rolled
+`useEffect` + `createElement('script')` blocks — with a decided answer for
+every mode the page can be in.
+
+```tsx
+import { Script } from '@voltro/web'
+
+// Analytics after hydration (the default strategy):
+<Script
+  src="https://eu.i.posthog.com/static/array.js"
+  onLoad={() => {
+    // The hand-written PostHog browser snippet — @voltro/plugin-posthog is a
+    // SERVER-side track sink and ships no browser snippet; this is the
+    // client half, wired the way PostHog's docs describe.
+    const w = window as { posthog?: { init: (key: string, opts: { api_host: string }) => void } }
+    w.posthog?.init('phc_your_project_key', { api_host: 'https://eu.i.posthog.com' })
+  }}
+/>
+
+// GTM bootstrap — the inline variant (id is REQUIRED: it is the dedupe key):
+<Script id="gtm-init">{`window.dataLayer = window.dataLayer || []`}</Script>
+
+// A chat widget nobody needs before the browser is idle:
+<Script src="https://widget.example.com/loader.js" strategy="lazyOnload" />
+```
+
+## Strategies
+
+- **`afterInteractive`** (default) — injected after this component mounts,
+  i.e. after hydration. Never render-blocking; the shell head stays clean.
+- **`lazyOnload`** — waits for browser idle (`requestIdleCallback`, with a
+  `setTimeout` fallback for Safari).
+
+There is **no `beforeInteractive`**. The honest alternative for a
+must-run-first script (a consent manager) is a literal `<script>` tag in the
+shell head — a `<link rel="preload">` is *not* an answer: it fetches but never
+executes. And no `worker` strategy (the Partytown class is its own decision).
+
+## Dedupe + remount semantics
+
+Scripts deduplicate **process-wide** by `src` (external) or `id` (inline) —
+the registry is global, so two `<Script>` tags for one widget produce one
+request and one execution, even across an islands page's separate bundle.
+
+A script is **never unloaded**. Navigate away and back and the script does
+not re-execute and nothing is re-fetched — but `onLoad` **fires again**,
+answered from the registry (the classic next/script bug where a remounted
+component's `onLoad` never fires is pinned by test here). `onError` behaves
+the same for a failed load.
+
+## Behavior per `interactive` mode — decided, not accidental
+
+- **`full`** — as described above.
+- **`none`** — zero-JS means zero: the app bundle never ships, so a
+  `<Script>` can never inject. The build **warns by name** instead of
+  silently doing nothing.
+- **`islands`** — outside an island nothing mounts, so a `<Script>` in the
+  page's static part never fires; the build warns. Inside an island it runs
+  when that island hydrates — a `visible` island's script loads when it
+  scrolls into view, which is often exactly the lazy behavior you want.
+
+## CSP
+
+`<Script>` injects client-side, so the per-request nonce your middleware
+mints ([CSP nonces](/docs/security/production-hardening)) is stamped into
+server-rendered tags — not into tags created in the browser. The component's
+answer:
+
+- An explicit `nonce` prop always wins.
+- Otherwise the injector propagates the **document's own nonce** (read off an
+  existing nonce'd script element). On an SSR page under a nonce'd CSP the
+  injected tag therefore carries the request's nonce automatically.
+- On a **`static` page there is no per-request nonce path at all** — the
+  documented options are `'strict-dynamic'` (scripts injected by an
+  allowed/nonce'd bootstrap are permitted, which is exactly this shape) or a
+  hash-based policy.
+
+The inline variant is covered by the same rules — under a strict CSP an
+inline snippet needs the nonce or `'strict-dynamic'` like any other injected
+script.
+
+
+
+---
+
+<!-- source: en/routing/fonts.md -->
+## Fonts
+
+_Self-hosted local fonts — declared once in app.config.ts, delivered as hashed woff2 with @font-face, a size-adjusted fallback face (the CLS guard), a preload link and opt-in subsetting. No font CDN request ever leaves the browser._
+
+Declare local font files once and the framework does the rest: content-hashed
+self-hosting, `@font-face` with `font-display`, a **size-adjusted fallback
+face** so the swap moves nothing, a `<link rel="preload">` in the shell head,
+and opt-in unicode-range subsetting.
+
+```ts
+// app.config.ts (web)
+export default {
+  type: 'web' as const,
+  name: 'MyApp',
+  fonts: [{
+    family: 'Inter',
+    src: [
+      { path: 'src/fonts/Inter-Variable.woff2', weight: '100 900' },  // variable range
+      // …or discrete faces — Regular+Bold is any real project's minimum:
+      // { path: 'src/fonts/Inter-400.woff2', weight: 400 },
+      // { path: 'src/fonts/Inter-700.woff2', weight: 700 },
+      // { path: 'src/fonts/Inter-Italic.woff2', weight: 400, style: 'italic' },
+    ],
+    display: 'swap',
+    subsets: ['latin'],
+    fallback: 'Arial',
+  }],
+}
+```
+
+```tsx
+import { localFont } from '@voltro/web'
+
+const inter = localFont('Inter')   // { variable: '--font-inter', fontFamily: 'var(--font-inter)' }
+
+export default function Page(): React.ReactElement {
+  return <main style={{ fontFamily: inter.fontFamily }}>…</main>
+}
+```
+
+The shell defines `--font-inter` as `'Inter', 'Inter Fallback', Arial,
+sans-serif` — use it from any CSS. Every render mode ships the same head tags
+(the CSS + preload are baked into the ONE generated shell that dev, static
+prerender, SSR streaming and `voltro start` all serve).
+
+## Why the fallback face matters (CLS)
+
+Until the web font arrives, text renders in the fallback — and a fallback
+with different metrics reflows the page when the swap happens. The pipeline
+reads the font file's real metrics (fontkit) and emits an `'Inter Fallback'`
+face: `local('Arial')` with `size-adjust`, `ascent-override`,
+`descent-override` and `line-gap-override` computed by the capsize formula so
+the fallback occupies the SAME space. The swap becomes invisible; CLS ≈ 0.
+
+## Subsetting
+
+`subsets: ['latin']` (and/or `'latin-ext'`) rewrites each face to just that
+unicode range via `subset-font`, declared with a matching `unicode-range` so
+the browser only downloads what the page's characters need. Measured in the
+framework's own e2e: the subset ships at well under half the source size.
+
+## GDPR — no font CDN, ever
+
+Nothing here talks to Google Fonts (or any font host) at runtime — the files
+ship from YOUR origin, content-hashed and immutable. That is the compliance
+answer German courts made concrete (LG München, remote Google-Fonts
+embedding): the user's IP never reaches a font CDN because no request leaves
+your domain. The framework's e2e asserts exactly that — a full page load with
+zero foreign-host requests.
+
+**Getting the files:** there is deliberately no Google-Fonts download helper
+(license terms differ per family — that step stays yours). The manual path:
+download the family from fonts.google.com (or the foundry), drop the
+`woff2`/`ttf` into `src/fonts/`, declare it. Done once, committed with the
+repo.
+
+## Tooling (optional, degrades loudly)
+
+`fontkit` (metrics) and `subset-font` (subsetting) ship as optional
+dependencies of @voltro/cli — script-free, nothing to approve. If your
+installer omits optional dependencies: fonts still self-host with
+`@font-face` + preload, but the fallback metrics and subsets are skipped —
+with ONE named warning each, and `voltro doctor` reports which half is
+missing and the fix. Never a silent downgrade.
+
+
+
 ---
 
 <!-- source: en/routing/middleware.md -->
 ## Middleware
 
-_'`middleware.ts` — the web app''s one server-only hook: renew a credential before the SSR render uses it, and say which routes it runs on.'_
+_'`middleware.ts` — the web app''s one server-only hook: renew a credential before the SSR render uses it, shape the response (headers, a CSP nonce), and say which routes it runs on.'_
 
-`middleware.ts` at the web app root runs **before** a server render binds its data. It exists for one job — renewing a credential — and it is deliberately narrow about everything else.
+`middleware.ts` at the web app root runs **before** a server render binds its data. It exists for two jobs — renewing a credential the render is about to use, and shaping the RESPONSE (`responseHeaders`, a `cspNonce`) — and it is deliberately narrow about everything else.
 
 ```ts
 // middleware.ts — server-only. NOT app.config.ts, which is imported into the
@@ -2017,7 +2678,7 @@ A cookie older than the IdP's token lifetime — practically every first page vi
 
 ## What it receives, and what it can return
 
-`run` gets a read-only request and returns `{ headers?, setCookies? }` — or nothing, to change nothing.
+`run` gets a read-only request and returns `{ headers?, setCookies?, responseHeaders?, cspNonce? }` — or nothing, to change nothing. `headers` and `setCookies` shape the REQUEST this render sees; `responseHeaders` and `cspNonce` shape the RESPONSE it produces (their own sections below).
 
 | Field | |
 |---|---|
@@ -2046,6 +2707,52 @@ The middleware produces one view of the request that everything downstream reads
 
 So a hook that renews **only** via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP — still authenticates this render's rpc calls: the `Cookie` header is rebuilt from the updated jar. A `maxAge` of `0` deletes, so a hook that signs someone out renders them signed out. If you return an explicit `cookie` header yourself, yours wins.
 
+## Response headers — `responseHeaders`
+
+`responseHeaders` is applied to what this render SENDS — every render-shaped response on both boot paths: `ssr` and `isr` renders, the `spa` shell, and a loader's redirect or 404.
+
+```ts
+export const session = defineMiddleware({
+  match: { under: '/app' },
+  run: async () => ({
+    responseHeaders: {
+      'x-frame-options': 'DENY',
+      'referrer-policy': 'no-referrer',
+    },
+  }),
+})
+```
+
+Two boundaries, stated rather than implied:
+
+- **`responseHeaders` act on the RENDER — an isr cache HIT does not re-run the middleware,** so a HIT does not carry the headers the MISS's render produced. For an `isr` page, either set cache-independent headers at the proxy, or accept that only MISS/refresh responses carry them.
+- **Prerendered `static` pages never render at request time,** so there is no middleware run to attach headers to. That is the documented proxy recipe: headers on static files belong on whatever serves them.
+
+## A per-request CSP nonce — `cspNonce`
+
+Return `cspNonce` and the framework stamps `nonce="…"` onto every script tag of that render — the state script, the deferred registry, the shell's bundle tags, and React's own bootstrap/settle scripts (via React's nonce support). The POLICY header stays yours: set it via `responseHeaders`, with the same nonce.
+
+```ts
+import { randomBytes } from 'node:crypto'
+import { defineMiddleware } from '@voltro/web/middleware'
+
+export const csp = defineMiddleware({
+  match: { under: '/app' },
+  run: async () => {
+    const nonce = randomBytes(16).toString('base64url')   // fresh per request
+    return {
+      cspNonce: nonce,
+      responseHeaders: {
+        'content-security-policy': `script-src 'nonce-${nonce}' 'strict-dynamic'`,
+      },
+    }
+  },
+})
+```
+
+- **`isr` + `cspNonce` refuses the render, loudly.** A cached nonce is a lie the browser enforces — the second visitor gets HTML whose nonce the policy header no longer matches. The ways out: `ssr` for nonce'd pages, or a hash-based CSP for `isr`.
+- The PPR variant of that question is open until partial prerendering exists; a component for client-injected script tags (a `Script` component) is planned.
+
 ## `match` — where it runs
 
 Without a `match`, a middleware runs on every server-rendered route, including your marketing pages. That is an IdP round trip on the page least able to afford one.
@@ -2115,3 +2822,114 @@ The file is loaded **once per boot** — it is app code with a stable identity,
 **`voltro dev` therefore RESTARTS when you edit it**, the same way a hard-restart field in `app.config.ts` does, and says so in the log. Once-per-boot is documented, and it is still the rule most easily forgotten — everything else in a dev server hot-reloads, so a sabotaged middleware that changes nothing reads as a hook that was never wired.
 
 It runs on both SSR boot paths, `voltro dev` and `voltro start`, with the cookies written on every response arm.
+
+
+
+---
+
+<!-- source: en/routing/intercepting-routes.md -->
+## Intercepting routes
+
+_Modal-with-URL — a page that opens as an overlay above the still-mounted origin on soft navigation, renders standalone on a hard load, and closes on Back; declared with one page export, no directory grammar._
+
+An intercepting route is the **modal-with-URL** pattern: navigating from a
+gallery to a photo opens the photo as an overlay *above the still-mounted
+gallery* — the URL is the photo's, sharing/reloading it shows the standalone
+photo page, and Back closes the overlay with the gallery exactly as you left
+it (typed filters, scroll position, mounted state — nothing re-runs).
+
+## Declaring one
+
+One export on the PAGE, no directory grammar:
+
+```tsx
+// src/pages/photos/[id]/page.tsx
+export const renderMode = 'ssr' as const
+export const intercept = { from: '/photos' }
+
+export const loader = ({ params }) => fetchPhoto(params.id)
+
+export default function PhotoDetail() {
+  const photo = useLoaderData<Photo>()
+  return <figure>…</figure>
+}
+```
+
+`from` names one or more ROUTE PATTERNS (`'/photos'`,
+`['/photos', '/albums/[id]']`). A soft navigation that arrives from one of
+them renders this page inside a native `<dialog>` overlay; a soft navigation
+from anywhere else — and every hard load — renders it standalone. That
+asymmetry is the feature: the same URL is a lightweight preview in context
+and a full page out of context.
+
+## The three paths, precisely
+
+- **Soft navigation from a `from` route** — the overlay opens. The origin
+  page stays MOUNTED: its state, subscriptions and scroll position are
+  untouched (the router keeps rendering it as the background tree; nothing
+  unmounts, no loader re-runs). Only the modal page's own loader runs —
+  layout loaders do not (the overlay renders the page alone above the
+  background's chrome), and its `Pending` shows *inside* the overlay, never
+  as a full-screen swap.
+- **Hard load / reload** — standalone, always. The server knows nothing of
+  interception; it renders the page as itself, with its own `meta`. A reload
+  of an open modal deliberately IGNORES the overlay state that survives in
+  `history.state` — the server rendered standalone and hydration must match
+  it.
+- **Back** — closes the overlay (it is a real history entry). Focus returns
+  to the element that opened it (native `<dialog>` semantics), the body
+  scroll lock releases, and the background — which never went anywhere —
+  needs no restore.
+
+Nested modals stack: a modal that soft-navigates to another intercepting
+route (its `from` naming the modal's pattern) opens above it, and Back
+closes only the topmost.
+
+## Navigation blockers hold the Back gesture
+
+`useBlocker` now guards **popstate** too. Back is a modal's primary close
+gesture, and before this it bypassed every blocker: the browser moves the
+URL first, so the router *reverts* the move (`history.go(-delta)`) when a
+blocker holds it and surfaces `retry`/`reset` as for any blocked navigation.
+ESC inside the overlay routes through the same path — a dirty form holds
+both. This is a behaviour CHANGE of a documented hook: a blocker that used
+to be silently skipped on Back now fires.
+
+## Two trees, two query strings
+
+While an overlay is open the URL carries the MODAL's query. Each tree reads
+its own: `useSearchParams` in the background keeps decoding the background's
+query (an open modal cannot reset a filter), and `useSetSearchParams` writes
+to the calling tree's URL — a background setter never writes onto the
+modal's URL, and a modal setter (a `?zoom=` tweak) replaces without tearing
+down its own background.
+
+## What it is NOT
+
+- **Parallel `@slot` routes are a declared non-goal.** Next.js pairs
+  interception with independent slot navigation (`@team`/`@analytics`,
+  per-slot `loading.tsx`/`default.tsx`). Here, dashboard split panes are
+  COMPONENTS in a layout, not a routing concept — this page delivers the
+  intercepting/modal half only.
+- **Islands / zero-JS pages don't intercept.** Interception is a client
+  router behaviour; `interactive: 'islands'` pages have no SPA navigation
+  and `'none'` ships no JS. Full-hydration pages only.
+- **Overlays do not View-Transition.** Route transitions apply to route
+  swaps; an overlay opening is a layer change, not a page change (see
+  [Navigation](/docs/routing/navigation)).
+
+## Chrome, focus, and styling
+
+The framework renders the overlay as a native `<dialog>` opened with
+`showModal()` — focus trap, `::backdrop` and focus restoration come from the
+platform, and the body scroll is locked while open. It is deliberately
+unstyled: target `dialog[data-vweb-overlay]` (and `::backdrop`) from your
+CSS or a kit. The route announcer announces the modal's title on open, as it
+would any navigation.
+
+## Locale-prefixed apps
+
+`from` matches route patterns literally, so a `[locale]` mirror declares its
+own: `/de/photos/[id]`'s page re-exports the base page and sets
+`intercept: { from: '/[locale]/photos' }` — same pattern as the documented
+searchParams schema re-export.