@voltro/cli 0.52.0 → 0.53.0

package/templates/agent-docs/routing.md

@@ -599,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
@@ -614,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
@@ -671,6 +674,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 +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.
@@ -2230,6 +2345,304 @@ 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 -->
@@ -2409,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.