@voltro/cli 0.15.0 → 0.17.0

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

@@ -39,7 +39,7 @@ apps/acme/web/                          # dir named by the app, not the template
 
 ## The page
 
-`src/pages/index.page.tsx` is plain JSX with the two static-render exports:
+`src/pages/page.tsx` is plain JSX with the two static-render exports:
 
 ```tsx
 export const renderMode  = 'static' as const   // pre-render at build time
@@ -59,7 +59,7 @@ export default function Index() {
       </section>
       <section>
         <h2>Ready to start?</h2>
-        <p>Edit <code>src/pages/index.page.tsx</code> to make it yours.</p>
+        <p>Edit <code>src/pages/page.tsx</code> to make it yours.</p>
       </section>
     </main>
   )
@@ -80,7 +80,7 @@ export default island(SignupForm, { name: 'SignupForm', hydrate: 'visible' })
 ```
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 export const interactive = 'islands' as const   // was 'none'
 import SignupForm from '../components/SignupForm.island'
 // … render <SignupForm /> somewhere in the page …
@@ -185,7 +185,7 @@ If your final product is going to be a:
 
 _A documentation site with a catch-all docs router and build-time static pre-rendering of every page via getStaticPaths._
 
-A documentation-site starter. `src/pages/docs/[...slug].page.tsx` is a catch-all router; `getStaticPaths` enumerates every doc URL at build time so `voltro build` pre-renders them all into a static site you can deploy anywhere. Template id: **`frontend-docs`**.
+A documentation-site starter. `src/pages/docs/[...slug]/page.tsx` is a catch-all router; `getStaticPaths` enumerates every doc URL at build time so `voltro build` pre-renders them all into a static site you can deploy anywhere. Template id: **`frontend-docs`**.
 
 The starter ships a tiny in-file `DOCS` array as stub content. Replace it with a real loader (a markdown reader, a CMS query, a database fetch) — the page component's contract stays the same.
 
@@ -215,7 +215,7 @@ apps/acme/docs/                         # dir named by the app, not the template
 
 ## The catch-all renderer
 
-`src/pages/docs/[...slug].page.tsx` is the whole engine. It declares:
+`src/pages/docs/[...slug]/page.tsx` is the whole engine. It declares:
 
 ```tsx
 export const renderMode  = 'static' as const   // pre-render at build
@@ -418,7 +418,7 @@ No rpc client, no loader, no `apis:` entry, no `@voltro/ui-shadcn` dependency. T
 The page exports `renderMode = 'spa'`, which tells `voltro build` not to pre-render it: the client renders it on load. Use this when the whole page is interactive AND its state lives in the browser — an SSR'd first paint would just be discarded on hydration, so rendering it on the server buys nothing.
 
 ```tsx
-// src/pages/index.page.tsx — a pure client-side SPA (a bill splitter)
+// src/pages/page.tsx — a pure client-side SPA (a bill splitter)
 import type { ReactNode } from 'react'
 import { useEffect, useState } from 'react'
 
@@ -603,7 +603,7 @@ The full reference for these modes lives in the [render modes guide](/docs/routi
 `index.tsx` exports `renderMode = 'ssr'`. Its loader runs SERVER-SIDE on EVERY request under `voltro start` — the timestamp and nonce change on each refresh, and the loader can read the incoming request to personalise the HTML before it's sent. There is no caching: the response carries `x-voltro-rendered-by: ssr`.
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, useServerRequest, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -646,7 +646,7 @@ Use SSR for anything that varies per request: a logged-in dashboard, a page that
 `feed.tsx` takes the SAME render path as SSR, but `voltro start` CACHES the HTML and serves the cached copy to every request within the `revalidate` window. After the window expires the next request re-renders and replaces the cache — cache hits return in well under a millisecond. `tenantAware: true` folds the `x-tenant` request header into the cache key, so tenant A's render is never served to tenant B:
 
 ```tsx
-// src/pages/feed.page.tsx
+// src/pages/feed/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -685,7 +685,7 @@ The loader's `headers` is populated server-side (lowercased keys) — that's how
 `feed-swr.tsx` is the same ISR page plus a `staleWhileRevalidate` window. When `revalidate` expires, instead of blocking the next visitor on a fresh render, the cache serves the STALE HTML immediately AND kicks off a background re-render. The visitor never waits; the cache catches up out-of-band. Beyond `revalidate + staleWhileRevalidate` the next request blocks on a fresh render, like a cold MISS:
 
 ```tsx
-// src/pages/feed-swr.page.tsx
+// src/pages/feed-swr/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -878,10 +878,10 @@ export const posts: ReadonlyArray<Post> = [
 
 ## SSG dynamic routes — `getStaticPaths` + `loader` + per-post `meta`
 
-A dynamic route like `src/pages/blog/[slug].page.tsx` matches infinitely many URLs. To pre-render it statically the build needs to know WHICH slugs exist — that is what `getStaticPaths` answers, by mapping over the content source. For each enumerated `params` the build runs the `loader` (server-side, at build time) and renders one HTML file. The `meta` export is a FUNCTION of the loader data, so each post gets its own correct `<title>` / `<description>` baked into the HTML — exactly what you want for SEO and social cards.
+A dynamic route like `src/pages/blog/[slug]/page.tsx` matches infinitely many URLs. To pre-render it statically the build needs to know WHICH slugs exist — that is what `getStaticPaths` answers, by mapping over the content source. For each enumerated `params` the build runs the `loader` (server-side, at build time) and renders one HTML file. The `meta` export is a FUNCTION of the loader data, so each post gets its own correct `<title>` / `<description>` baked into the HTML — exactly what you want for SEO and social cards.
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, notFound, type LoaderFn, type PageMeta } from '@voltro/web'
 import { posts, type Post } from '../../content/posts'
@@ -972,7 +972,7 @@ export default island(ReadingProgress, { name: 'ReadingProgress', hydrate: 'load
 The index at `/` is pure content: a list of posts with no interactivity. It declares `interactive: 'none'`, which makes the framework strip EVERY `<script>` it would otherwise emit — the HTML ships with no JS bundle at all. It reads the same content source the `[slug]` page + `getStaticPaths` use:
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import { posts } from '../content/posts'
@@ -1106,10 +1106,10 @@ The serverless function lives next to the web app but is a separate deploy artif
 
 ## The static page + the island form
 
-`src/pages/index.page.tsx` is `renderMode: 'static'` (pre-rendered, servable from a CDN) and `interactive: 'islands'` — so only the `<ContactForm>` island hydrates; the headline + copy ship as inert HTML with no React lifecycle:
+`src/pages/page.tsx` is `renderMode: 'static'` (pre-rendered, servable from a CDN) and `interactive: 'islands'` — so only the `<ContactForm>` island hydrates; the headline + copy ship as inert HTML with no React lifecycle:
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import ContactForm from '../components/ContactForm.island'
@@ -1358,7 +1358,7 @@ apps/demo/web/
 ├── README.md
 └── src/pages/
     ├── layout.tsx                 # root shell (header + <main>)
-    └── index.page.tsx                  # the reactive page — useSubscription + useMutation
+    └── page.tsx                  # the reactive page — useSubscription + useMutation
 ```
 
 ## The `apis` wiring
@@ -1390,7 +1390,7 @@ The `package` resolves the api workspace package; its port is auto-discovered fr
 ## The reactive loop
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import { useMutation, useSubscription } from '@voltro/client'
 
 const TENANT = 'acme'
@@ -1418,7 +1418,7 @@ The subscription builder also exposes `revision`, `emittedAt`, `error`, and `pen
 
 ## Pairing with a different api
 
-This page is wired to api-backend's `notes` domain. To point it at your own api, change `apis.app.package` in `app.config.ts`, then swap the rpc tags + the row type in `src/pages/index.page.tsx` to match your descriptors. The hook shapes are identical for any api.
+This page is wired to api-backend's `notes` domain. To point it at your own api, change `apis.app.package` in `app.config.ts`, then swap the rpc tags + the row type in `src/pages/page.tsx` to match your descriptors. The hook shapes are identical for any api.
 
 ## When to use
 
@@ -1533,7 +1533,7 @@ export const withLocalePrefix = (path: string, locale: string): string =>
 Each page has a one-line **mirror** under `src/pages/[locale]/`. The mirror re-exports the bare page verbatim (the component reads its locale from the URL via the layout's provider) and uses `getStaticPaths` to enumerate the *non-default* locales — which is what tells `voltro build` to emit the `/de/...` HTML. Without the mirror, only the default-locale URL is built.
 
 ```tsx
-// src/pages/[locale]/index.page.tsx — the entire file
+// src/pages/[locale]/page.tsx — the entire file
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
 
 export { default } from '../index'
@@ -1550,7 +1550,7 @@ export const getStaticPaths = async (): Promise<Array<{ params: { locale: string
 The body of each page is localised automatically (the SSG pipeline wraps every variant in the right catalog's provider). The document head is NOT — unless you export `meta` as a **function of `{ locale }`**. The framework drives `locale` from `params.locale` on the `[locale]` route (and `defaultLocale` on the bare path), so each variant bakes the right `<title>` / `<meta description>` into its HTML — exactly what you want for SEO and social cards. A plain `meta` object would leave the head English on `/de`.
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import { T, useT, useLocale } from '@voltro/i18n'
 import { getCatalog } from '../lib/locale'
 
@@ -1662,7 +1662,7 @@ The `[locale]` mirrors pick it up automatically — `getStaticPaths` reads `SUPP
 
 ## Anti-patterns
 
-- **Forgetting the `[locale]` mirror for a new page.** Create `src/pages/foo.page.tsx` AND a one-line mirror `src/pages/[locale]/foo.page.tsx`. Without the mirror, only the default-locale URL is emitted — `/de/foo` 404s.
+- **Forgetting the `[locale]` mirror for a new page.** Create `src/pages/foo/page.tsx` AND a one-line mirror `src/pages/[locale]/foo/page.tsx`. Without the mirror, only the default-locale URL is emitted — `/de/foo` 404s.
 - **Exporting `meta` as a plain object.** The body localises, but the `<title>` / `<meta description>` stay English on `/de`. Export `meta` as a function of `{ locale }` and read the catalog via `getCatalog(locale)`.
 - **Skipping `defineLocale<typeof en>()` for a non-base catalog.** Plain `defineCatalog(...)` compiles but loses the parity check — the one feature that stops translations drifting. Always run non-base locales through `defineLocale<typeof en>()`.
 - **Angle brackets in catalog strings.** react-intl's ICU parser treats `<tag>` as a rich-text element and fails (`FORMAT_ERROR`) if there's no matching close tag. Write "page titles", not "`<title>` tags", in a message.
@@ -1759,7 +1759,7 @@ export default function DashboardLayout({ children }) {
 The gate must run **per request** — it reads the request's cookie and may redirect. A `static` page is pre-rendered once at build time with no per-visitor render, so it can't redirect per-visitor; in fact `voltro build` **rejects** a `RedirectError` thrown during static pre-render. So the authed pages declare `renderMode: 'ssr'`:
 
 ```tsx
-// src/pages/dashboard/index.page.tsx
+// src/pages/dashboard/page.tsx
 export const renderMode = 'ssr' as const
 export const meta = { title: 'Overview' }
 export default function Overview() { /* … */ }
@@ -1884,7 +1884,7 @@ export default {
 `query` is present ONLY server-side (`ssr` / `isr`). It invokes the api's rpc directly over `POST /rpc`, **forwarding the request's session cookie** so the same Subject + tenant resolve as the WebSocket path. A streaming query is drained to its FIRST snapshot — here, the current notes for this tenant. `meta` reads the result, so the `<title>` reflects real data in the server-rendered HTML:
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 import { useSubscription } from '@voltro/client'
 
@@ -1994,7 +1994,7 @@ const entities = manifest ? deriveEntityAdmins(manifest) : []
 ## Per-entity CRUD
 
 ```tsx
-// src/pages/admin/[entity].page.tsx (abridged)
+// src/pages/admin/[entity]/page.tsx (abridged)
 const canCreate = useCan(spec.createScope)         // <table>:create
 {spec.createTag && canCreate ? (
   <AutoForm api="app" mutation={spec.createTag} submitLabel={`Add ${spec.table}`} />
@@ -2041,7 +2041,7 @@ apps/acme/web/
 
 ## Make it yours
 
-Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts`) + demo scopes (`lib/admin.ts`) for real auth; replace the generic `[entity].page.tsx` with a hand-built page for any entity that needs more than CRUD.
+Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts`) + demo scopes (`lib/admin.ts`) for real auth; replace the generic `[entity]/page.tsx` with a hand-built page for any entity that needs more than CRUD.
 
 ## When to use frontend-admin vs. the other web templates