@voltro/cli 0.52.0 → 0.54.0

package/templates/agent-docs/routing.md

@@ -245,6 +245,36 @@ export { searchParams } from '../../search/page'
 
 One schema, no drift — the mirror page decodes exactly what the original declares.
 
+**Two scanners read this line, and they do not agree.** The isr refusal above is a
+source scan, and so is the route-builder codegen that brands a route's URL with its
+searchParams type — but they recognise different spellings, which is worth knowing
+before you pick one:
+
+| spelling on the mirror page | typed `withQuery` on the mirror route | `isr` + schema refused |
+| --- | --- | --- |
+| `export const searchParams = …` | yes | yes |
+| `export { searchParams } from '../../search/page'` | **no** | yes |
+| `export * from '../../search/page'` | **no** | **no** |
+| `import { searchParams as base } …` + `export const searchParams = base` | yes | yes |
+
+The middle two are the ones to watch. A clause re-export still decodes correctly at
+runtime and is still refused on `isr` — but the route builder does not see it, so
+`withQuery` on the mirror's URL falls back to untyped and nothing reports it. A star
+re-export is seen by neither: the binding is on the module at runtime (`export *`
+forwards every named export), so the page behaves as if it declared a schema while
+the `isr` refusal never fires.
+
+So: prefer the last row when you want the mirror route's links type-checked, and
+never reach a schema through `export *` on an `isr` page.
+
+```tsx
+// src/pages/[locale]/search/page.tsx — one schema, and both scanners see it
+import { searchParams as base } from '../../search/page'
+
+export const searchParams = base
+export { default } from '../../search/page'
+```
+
 ### Routes without a schema
 
 `useSearchParams()` without an argument stays the raw `URLSearchParams` — nothing changes for a route that declares no schema:
@@ -521,7 +551,7 @@ export const renderMode = 'static' as const   // 'static' | 'spa' | 'ssr' | 'isr
 | `ssr` | Every request | Never | Authenticated dashboards, search results, anything cookie-driven |
 | `isr` | First request after build, then on revalidate | Per-key in-memory or Postgres | News feeds, listings, dashboards that change but not per-user |
 
-Those four are the **complete** set. An unrecognised value is a hard error naming the page — see [What doesn't work](#what-doesnt-work).
+Those four are the **complete** set. An unrecognised value is a hard error naming the page — see [What doesn't work](#what-doesn-t-work).
 
 ## static (SSG)
 
@@ -599,7 +629,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
@@ -614,8 +644,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
@@ -671,6 +704,69 @@ the first visitor's data for everyone. This applies identically under
 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):
@@ -1474,6 +1570,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.
@@ -1947,7 +2092,7 @@ export const interactive = 'islands' as const
 
 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.
+Looking for Astro's **"Server Islands"** — per-request-rendered holes in otherwise static pages? In Voltro that is [**partial prerendering (PPR)**](/docs/routing/render-modes#partial-prerendering-ppr-cached-shell-per-request-holes): `ppr = true` on an `isr` page, a separate mechanism from islands mode. The two do not combine — ppr reveals its holes through hydration, so it requires `interactive: 'full'`.
 
 ## When to use islands
 
@@ -2230,6 +2375,309 @@ 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 into
+  `dist/assets/content-media/<hash>.<ext>` by the content pipeline and the
+  `src` rewritten to that URL. A relative source resolves against the markdown
+  file that references it, and one that does not exist FAILS the build naming
+  the path — a page that renders while its image 404s is the outcome this
+  replaces. Absolute (`/…`) and remote sources are left untouched. Build-time
+  TRANSFORMATION (resize / format) stays a named non-goal here: a markdown
+  reference carries no width and no `sizes` to derive one from.
+
+## `<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 -->
@@ -2317,7 +2765,7 @@ Two boundaries, stated rather than implied:
 
 ## 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.
+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, the islands entry, and React's own bootstrap and Suspense 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'
@@ -2338,7 +2786,9 @@ export const csp = defineMiddleware({
 ```
 
 - **`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.
+- **`ppr` is refused for the same reason.** A [partial-prerendered](/docs/routing/render-modes#partial-prerendering-ppr-cached-shell-per-request-holes) page serves a cached shell whose inline registry scripts cannot carry a per-request nonce, so `cspNonce` on a `ppr` page is refused by name — same ways out as `isr`.
+- **Client-injected script tags carry the nonce too.** [`<Script>`](/docs/routing/third-party-scripts) propagates the DOCUMENT's own nonce onto the tag it injects, so a nonce'd `ssr` page needs no explicit `nonce` prop.
+- **`defer()` does not yet compose with `cspNonce`.** The settle `<script>` each [`<Await>`](/docs/routing/loaders-and-meta) boundary emits inside the streamed body is part of the RENDERED TREE — it is not one React injects, so React's nonce support does not reach it, and it is not in the `<head>` the framework stamps. Under `script-src 'nonce-…'` the browser blocks it, the deferred value is never published to the client registry, and the boundary stays on its fallback after hydration while the server HTML looks correct. Until that is closed, pick one per route: `defer()`, or a nonce'd CSP.
 
 ## `match` — where it runs
 
@@ -2409,3 +2859,131 @@ 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' }`.
+
+**Declares — not re-exports.** `intercept` is read off the page module at
+runtime, so any re-export forwards it, `export *` included. A mirror that
+forwards the base page's `intercept` therefore inherits `from: '/photos'`, and
+`from` is compared against the background's route PATTERN, which for a mirror is
+`/[locale]/photos`. The two never match, so the overlay silently never opens and
+the modal renders standalone — no error, no warning, just a page where a modal
+was expected. This is the opposite failure from the [searchParams
+re-export](/docs/routing/pages#mirror-routes-share-one-schema), which is silently
+*lost*; `intercept` is silently *inherited with the wrong pattern*.
+
+```tsx
+// src/pages/[locale]/photos/[id]/page.tsx
+export { default, meta } from '../../../photos/[id]/page'
+
+// NOT re-exported: the base's `from` names the un-prefixed pattern.
+export const intercept = { from: '/[locale]/photos' }
+```

package/templates/agent-docs/scheduling.md

@@ -214,7 +214,7 @@ The handler receives a `ScheduleContext` — the same `app` a mutation gets, plu
 > tenant-scoped** — a schedule runs as `system` with no tenant. Reads see every
 > tenant's rows, and a write to a `tenant()` table fails with
 > `TenantScopeViolation` unless you pass `tenantId` explicitly. See
-> [below](#a-schedule-runs-as-the-system-subject--no-tenant). This sentence is
+> [below](#a-schedule-runs-as-the-system-subject-no-tenant). This sentence is
 > here rather than only further down because "same shape as a mutation" is what
 > sets the expectation that gets violated.