@voltro/cli 0.53.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)
 
@@ -2062,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
 
@@ -2449,9 +2479,14 @@ passthrough.
   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.
+- **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
 
@@ -2730,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'
@@ -2751,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
 
@@ -2931,5 +2968,22 @@ would any navigation.
 
 `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.
+`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.
 

package/templates/agent-docs/schema-driven-ui.md

@@ -419,7 +419,18 @@ the SAME input schema the RPC path decodes:
 - unknown keys are dropped
 
 Validation runs through the same `validateFields` as the client-side
-validation, so the error texts are identical. Then:
+validation, so the error texts are identical — in the request's language, not
+in English. The handler resolves the locale from THIS request through the same
+resolver that decided the surrounding page's language ([`voltro:locale` cookie
+› `Accept-Language` › the app's
+`defaultLocale`](/docs/i18n/overview#locale-resolution-order)); an app that
+configures no `locales` gets `en`. Then:
+
+Under URL-prefix i18n the referring URL wins over the cookie chain: a form on
+`/de/todos` renders its errors in German even if the `voltro:locale` cookie says
+otherwise, because there the prefix is which page you are on rather than a
+preference. A first segment that is not a declared locale falls through to the
+cookie chain.
 
 - **Success → `303 See Other`** (POST-redirect-GET): back to the submitting
   page, or to `redirectTo` (same-origin relative paths only; anything else is

package/templates/agent-docs/templates/appshells.md

@@ -13,7 +13,7 @@ _A marketing landing page — hero, features, CTA. Static-rendered with zero JS
 
 A marketing landing page. The page exports `renderMode = 'static'` + `interactive = 'none'`, so `voltro build` pre-renders it to HTML and `voltro start` serves the file directly — zero framework JS on the wire. Template id: **`frontend-landing`**.
 
-It ships plain JSX (a hero, a features list, a CTA) you replace with your own copy — no design-system dependency to fight. When you need a contact form or sign-up flow, switch `interactive: 'islands'` on the page and mark the interactive component with a `*.island.tsx` suffix so only that bundle ships.
+It ships plain JSX (a hero, a features list, a CTA) you replace with your own copy, bilingual out of the box (URL-prefix i18n: `/` + `/de`), plus the two asset pipelines a marketing page actually needs: a **local hero image** through `?image` + `<Image>` and a **self-hosted woff2** declared under `fonts:`. When you need a contact form or sign-up flow, switch `interactive: 'islands'` on the page and mark the interactive component with a `*.island.tsx` suffix so only that bundle ships.
 
 ## Scaffold
 
@@ -27,14 +27,21 @@ voltro add-app marketing --template=frontend-landing --to acme
 
 ```text
 apps/acme/web/                          # dir named by the app, not the template
-├── app.config.ts                       # type:web, port:<allocated>
+├── app.config.ts                       # type:web, port:<allocated>, locales, fonts:
 ├── package.json
 ├── tsconfig.json
 └── src/
     ├── globals.css
+    ├── globals.d.ts                    # ambient '*.css' + '*?image'
+    ├── assets/hero.jpg                 # imported with ?image (build-time pipeline)
+    ├── fonts/Geist-Variable.woff2      # self-hosted, declared in app.config.ts
+    ├── fonts/LICENSE-Geist.txt         # the face's licence, shipped beside it
+    ├── lib/locale.ts                   # URL-prefix i18n helpers
+    ├── locales/{en,de}.ts              # the two catalogs
     └── pages/
         ├── layout.tsx                  # imports globals.css, renders {children}
-        └── index.tsx                   # the landing page (hero · features · CTA)
+        ├── page.tsx                    # the landing page (hero · features · CTA)
+        └── [locale]/page.tsx           # the /de mirror
 ```
 
 ## The page
@@ -88,9 +95,34 @@ import SignupForm from '../components/SignupForm.island'
 
 The surrounding HTML stays static; only the island hydrates.
 
+## The hero image — `?image` + `<Image>`
+
+`src/assets/hero.jpg` is imported with the **`?image` suffix**, the explicit opt-in to the [build-time image pipeline](/docs/routing/assets): the import resolves to an optimized-asset object instead of vite's plain hashed URL, and `<Image>` renders it as a `<picture>` with one `<source>` per modern format.
+
+```tsx
+import { Image } from '@voltro/web'
+import hero from '../assets/hero.jpg?image'
+
+<Image src={hero} alt="Abstract gradient artwork" priority sizes="(max-width: 900px) 100vw, 900px" />
+```
+
+`width`, `height` and the blur placeholder are **not props** — they come off the asset, which is what reserves the box (CLS ≈ 0) without hand-written numbers. `priority` marks it the LCP image (eager + high fetch priority). Nothing here needs JS, so it survives `interactive: 'none'`.
+
+The `*?image` ambient type is declared once in `src/globals.d.ts`. A **dynamic** `src` (a URL from a loader or CMS frontmatter) cannot be seen at build time — use the loader seam (`<Image src={url} loader={cdn} />`) instead.
+
+> **Under `voltro test`** the image plugin is not wired (it is a dev/build transform), so a `?image` specifier resolves to a plain URL string. The shipped `page.test.tsx` `vi.mock`s the import with the asset object the pipeline produces — copy that pattern rather than hand-writing `width`/`height` on the page.
+
+## The font — self-hosted, no CDN
+
+`app.config.ts` declares one family under [`fonts:`](/docs/routing/fonts), pointing at the woff2 committed in `src/fonts/`. The build content-hashes it and serves it from **your origin**, emits `@font-face`, computes a size-adjusted fallback face from the file's real metrics so the swap moves no text, and puts a `<link rel="preload">` in the shell.
+
+Reference it from CSS through the `--font-geist` variable the shell defines (`globals.css` points the kit's `--font-sans` at it), or from TSX with `localFont('Geist')`.
+
+**Swapping in your own face:** drop the `woff2` **and its licence file** into `src/fonts/`, then change `family` + `path`. The framework ships no font downloader on purpose — licence terms differ per family. The bundled Geist is SIL OFL 1.1 (`src/fonts/LICENSE-Geist.txt`).
+
 ## Styling
 
-`globals.css` is yours. Add `@import "tailwindcss"` plus the mandatory `@source "./**/*.{tsx,ts,jsx,js}"` glob if you want Tailwind, or `@import "@voltro/ui-shadcn/tokens.css"` (plus the kit `@source`) to pull in the design tokens and compose shadcn-style components on top.
+`globals.css` imports `@voltro/ui-shadcn/tokens.css` (the design tokens) plus the mandatory `@source "./**/*.{tsx,ts,jsx,js}"` glob. Drop the kit import and use `@import "tailwindcss"` directly if you would rather start from nothing — but keep the `@source` line either way, and keep the `--font-sans` mapping if you keep the font declaration.
 
 ## What it doesn't ship