@voltro/cli 0.50.1 → 0.52.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
 
@@ -637,6 +652,25 @@ 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'`.
+
 ## Tenant-aware ISR
 
 For multi-tenant ISR (each tenant gets its own cache entry):
@@ -662,6 +696,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
@@ -1423,7 +1514,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 +1529,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 +1676,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 +1797,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 +1835,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 +1869,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 +1941,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.**
+> **Islands cut hydration WORK and DOWNLOAD — the page ships its own lean entry.**
 >
-> `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.
->
-> 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 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.
+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.
+
+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 +1955,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 +1983,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 +2014,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 +2029,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 +2099,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 +2135,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
 
@@ -1987,9 +2235,9 @@ the `@source` is misconfigured.
 <!-- 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 +2265,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 +2294,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.