@voltro/cli 0.1.0

package/templates/apps/frontend-spa/src/pages/index.test.tsx

@@ -0,0 +1,137 @@
+// @vitest-environment jsdom
+//
+// `/` — the SPA bill-splitter. A 100% client-side page (`renderMode='spa'`)
+// built from React state + localStorage; no rpc client, no loader, no
+// framework hooks. We assert the config export, that it renders, and — the
+// real observable behavior — that entering a bill + choosing a tip preset +
+// people count updates the computed per-person total.
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../locales/en'
+
+import BillSplitter, { renderMode } from './index'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>, so it needs an <I18nProvider>. Wrap with the real English
+// catalog (the framework auto-wires this provider in the running app).
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+// Native value setter so React's onChange sees the programmatic update.
+const setInput = (el: HTMLInputElement, value: string): void => {
+  const setter = Object.getOwnPropertyDescriptor(
+    window.HTMLInputElement.prototype,
+    'value',
+  )!.set!
+  act(() => {
+    setter.call(el, value)
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+  })
+}
+
+// This Node build's jsdom does not provide localStorage (it needs
+// --localstorage-file). The page talks to the standard Web Storage API, so we
+// install a spec-compliant in-memory Storage — the same surface a browser gives
+// it — and exercise the real persistence path against it.
+let hadLocalStorage: boolean
+
+beforeEach(() => {
+  hadLocalStorage = typeof window.localStorage !== 'undefined'
+  if (!hadLocalStorage) {
+    const store = new Map<string, string>()
+    const storage: Storage = {
+      get length() {
+        return store.size
+      },
+      clear: () => store.clear(),
+      getItem: (k) => (store.has(k) ? store.get(k)! : null),
+      key: (i) => Array.from(store.keys())[i] ?? null,
+      removeItem: (k) => {
+        store.delete(k)
+      },
+      setItem: (k, v) => {
+        store.set(k, String(v))
+      },
+    }
+    Object.defineProperty(window, 'localStorage', { configurable: true, value: storage })
+  }
+  window.localStorage.clear()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+  if (!hadLocalStorage) {
+    Reflect.deleteProperty(window, 'localStorage')
+  }
+})
+
+describe('index — config export', () => {
+  test('is a client-only SPA page', () => {
+    expect(renderMode).toBe('spa')
+  })
+})
+
+describe('index — render', () => {
+  test('renders the bill-splitter heading and the tip presets', () => {
+    render(createElement(BillSplitter))
+    expect(container.querySelector('h1')!.textContent).toBe('Bill splitter')
+    const presetButtons = Array.from(
+      container.querySelectorAll('.presets button'),
+    ).map((b) => b.textContent)
+    expect(presetButtons).toEqual(['10%', '15%', '18%', '20%'])
+  })
+})
+
+describe('index — computed split', () => {
+  test('computes the per-person total from bill, tip preset, and people', () => {
+    render(createElement(BillSplitter))
+
+    // $100 bill.
+    setInput(container.querySelector('#bill') as HTMLInputElement, '100')
+
+    // Choose the 20% preset.
+    const twentyPct = Array.from(container.querySelectorAll('.presets button')).find(
+      (b) => b.textContent === '20%',
+    ) as HTMLButtonElement
+    act(() => { twentyPct.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+
+    // 4 people.
+    setInput(container.querySelector('#people') as HTMLInputElement, '4')
+
+    // total = 100 + 20% = 120; per-person = 30.
+    const perPerson = container.querySelector('.result .big')!.textContent ?? ''
+    expect(perPerson).toContain('30')
+    expect(container.textContent).toContain('120') // total tip+bill shown
+  })
+
+  test('persists the chosen tip % to localStorage', () => {
+    render(createElement(BillSplitter))
+    const tenPct = Array.from(container.querySelectorAll('.presets button')).find(
+      (b) => b.textContent === '10%',
+    ) as HTMLButtonElement
+    act(() => { tenPct.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    const stored: string[] = []
+    for (let i = 0; i < window.localStorage.length; i++) {
+      const key = window.localStorage.key(i)
+      if (key !== null) stored.push(window.localStorage.getItem(key) ?? '')
+    }
+    expect(stored).toContain('10')
+  })
+})

package/templates/apps/frontend-spa/src/pages/index.tsx

@@ -0,0 +1,123 @@
+// A pure client-side SPA — a bill splitter.
+//
+// `renderMode = 'spa'` tells `voltro build` NOT to pre-render this page:
+// the client renders it on load. That is the right choice here because the
+// whole page is interactive and its state lives in the browser
+// (localStorage) — an SSR'd first paint would just be discarded on
+// hydration, so rendering it on the server buys nothing.
+//
+// No backend, no rpc client, no loader. Just React + the browser.
+
+import type { ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+// Locale-aware tab title: @voltro/web resolves meta({ locale }) from the
+// active locale (the `voltro:lang` cookie in this cookie-i18n app).
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.home.title'],
+})
+
+export const renderMode = 'spa' as const
+// `interactive` defaults to 'full' — every component hydrates. That is
+// correct for an SPA where the whole tree is interactive (don't reach for
+// islands here; islands only help when most of the page is static).
+
+const TIP_PRESETS = [10, 15, 18, 20] as const
+const STORAGE_KEY = '{{appName}}:last-tip'
+
+const money = (n: number): string =>
+  Number.isFinite(n) ? n.toLocaleString(undefined, { style: 'currency', currency: 'USD' }) : '—'
+
+export default function BillSplitter(): ReactNode {
+  const [bill, setBill] = useState('')
+  const [tipPct, setTipPct] = useState(18)
+  const [people, setPeople] = useState(2)
+
+  // Restore the last tip % from localStorage — client-only, so read it in
+  // an effect (it never runs on the server).
+  useEffect(() => {
+    const saved = Number(window.localStorage.getItem(STORAGE_KEY))
+    if (Number.isFinite(saved) && saved > 0) setTipPct(saved)
+  }, [])
+
+  useEffect(() => {
+    window.localStorage.setItem(STORAGE_KEY, String(tipPct))
+  }, [tipPct])
+
+  const billNum = Math.max(0, Number(bill) || 0)
+  const headcount = Math.max(1, people)
+  const tip = billNum * (tipPct / 100)
+  const total = billNum + tip
+  const perPerson = total / headcount
+
+  return (
+    <div className="card">
+      <h1><T id="home.heading" /></h1>
+      <p className="muted"><T id="home.subtitle" /></p>
+
+      <label htmlFor="bill"><T id="field.bill" /></label>
+      <input
+        id="bill"
+        type="number"
+        inputMode="decimal"
+        min="0"
+        step="0.01"
+        placeholder="0.00"
+        value={bill}
+        onChange={(e) => setBill(e.target.value)}
+      />
+
+      <label><T id="field.tip" /></label>
+      <div className="presets">
+        {TIP_PRESETS.map((p) => (
+          <button
+            key={p}
+            type="button"
+            className={p === tipPct ? 'active' : ''}
+            onClick={() => setTipPct(p)}
+          >
+            {p}%
+          </button>
+        ))}
+      </div>
+
+      <div className="row">
+        <div>
+          <label htmlFor="custom"><T id="field.custom" /></label>
+          <input
+            id="custom"
+            type="number"
+            min="0"
+            max="100"
+            value={tipPct}
+            onChange={(e) => setTipPct(Math.max(0, Number(e.target.value) || 0))}
+          />
+        </div>
+        <div>
+          <label htmlFor="people"><T id="field.people" /></label>
+          <input
+            id="people"
+            type="number"
+            min="1"
+            value={people}
+            onChange={(e) => setPeople(Math.max(1, Math.floor(Number(e.target.value) || 1)))}
+          />
+        </div>
+      </div>
+
+      <div className="result">
+        <div className="col">
+          <span className="line"><span className="muted"><T id="result.tip" /></span><span>{money(tip)}</span></span>
+          <span className="line"><span className="muted"><T id="result.total" /></span><span>{money(total)}</span></span>
+        </div>
+        <div style={{ textAlign: 'right' }}>
+          <div className="muted"><T id="result.perPerson" /></div>
+          <div className="big">{money(perPerson)}</div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/templates/apps/frontend-spa/src/pages/layout.tsx

@@ -0,0 +1,27 @@
+// Root layout — imports globals.css. The SPA renders entirely client-side,
+// so there is no SSR document to worry about here.
+//
+// The app is bilingual (see `locales` in app.config.ts): <LocaleSwitcher>
+// writes the `voltro:lang` cookie + reloads so the framework re-renders in the
+// chosen language.
+
+import type { ReactNode } from 'react'
+import { useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import '../globals.css'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <>
+      <header style={{ display: 'flex', justifyContent: 'flex-end', padding: '12px 16px' }}>
+        <LocaleSwitcher locales={LOCALES} current={useLocale()} ariaLabel={useT('lang.label')} />
+      </header>
+      {children}
+    </>
+  )
+}

package/templates/apps/frontend-spa/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-spa",
+  "kind": "web",
+  "summary": "Pure client-rendered SPA (renderMode: 'spa') — a fully interactive standalone tool with NO backend and NO SSR. Shows where a single-page app is the right call: state lives in the browser (localStorage), so server rendering would just be discarded on hydration.",
+  "tags": ["web", "frontend", "spa", "client", "interactive", "standalone"]
+}

package/templates/apps/frontend-spa/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", ".framework"]
+}

package/templates/apps/frontend-ssr/README.md

@@ -0,0 +1,68 @@
+# {{projectName}} / {{appName}}
+
+Server-rendered pages (template: **frontend-ssr**) — the **SSR** and **ISR**
+render modes. Unlike a static site, these render on a runtime, so you serve
+them with `voltro start` (or the cloud), NOT a bare CDN.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev      # dev server with HMR
+
+# Production behaviour (the SSR/ISR cache only runs here):
+pnpm --filter @{{projectName}}/{{appName}} build
+pnpm --filter @{{projectName}}/{{appName}} start    # → voltro start
+```
+
+Then watch the response headers (`curl -i`):
+
+```bash
+curl -i http://localhost:5190/        | grep x-voltro    # x-voltro-rendered-by: ssr
+curl -i http://localhost:5190/feed    | grep x-voltro    # x-voltro-cache: MISS, then HIT
+```
+
+## What this template demonstrates
+
+| Page | Mode | Concept |
+|---|---|---|
+| `/` | `ssr` | Fresh per request; `useServerRequest()` reads cookies + headers server-side |
+| `/feed` | `isr` + `revalidate` + `tenantAware` | Cached HTML, revalidated on a window, per-tenant cache key |
+| `/feed-swr` | `isr` + `staleWhileRevalidate` | Serve stale instantly, refresh in the background |
+
+Response headers to look for: `x-voltro-rendered-by`, `x-voltro-cache`
+(`HIT` / `MISS` / `STALE` / `BYPASS`), `x-voltro-cache-age-ms`.
+
+## Pulling fresh data from your api
+
+This template is self-contained (loaders compute their own data), so it boots
+with zero infra. To render from YOUR reactive backend, declare an `apis` entry
+in `app.config.ts` and call `ctx.query` in an ssr/isr loader — it runs
+server-side, invokes the api's rpc directly, and forwards the session cookie:
+
+```ts
+// app.config.ts:  apis: { app: { package: '@{{projectName}}/api' } }
+export const loader: LoaderFn<Data> = async ({ query }) => ({
+  post: await query!('posts.get', { id: '…' }),   // `query` is server-only
+})
+```
+
+Scaffold the pair in one command:
+
+```bash
+voltro create-project {{projectName}} --api api-backend --web frontend-ssr
+```
+
+## Also available: CDC-driven cache invalidation
+
+An ISR page can declare `export const cacheInvalidatesOn = ['todos']` — the
+cached HTML drops the instant ANY write to those tables fires (needs an api
+with CDC). It pairs with a long `revalidate` for "reactive cache" semantics:
+cached arbitrarily long, fresh the moment the source data changes.
+
+## Don't ship these to a pure CDN
+
+`voltro static deploy` will refuse — SSR/ISR pages need a runtime to render per
+request. That gate is correct; serve them on `voltro start` / a container, and
+push only your `static` pages to a CDN. `voltro deploy plan` tells you which
+tier each page lands in.

package/templates/apps/frontend-ssr/app.config.ts

@@ -0,0 +1,32 @@
+// Web app for the {{projectName}} project — SERVER-RENDERED pages.
+//
+// Pages here use `renderMode: 'ssr'` (fresh per request) and `'isr'`
+// (cached + revalidated). Unlike a static site, these need a runtime —
+// run them with `voltro start` (NOT a bare CDN). The render-mode gate in
+// `voltro static deploy` will (correctly) refuse to ship them to a pure CDN.
+//
+// Self-contained: no `apis` declared, so it boots with zero infra. To pull
+// fresh data from YOUR reactive backend instead, add an `apis` entry and use
+// `ctx.query(...)` in the loaders (see src/pages/index.tsx).
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+  // Bilingual by default. The framework auto-wires a cookie-driven
+  // <I18nProvider> from these codes and loads the matching
+  // `src/locales/<code>.ts` catalog — so `<T id="…" />` / `useT()` /
+  // `useLocale()` work app-wide (SSR + ISR too) with no manual setup. The
+  // <LocaleSwitcher> in the layout writes the `voltro:lang` cookie + reloads.
+  // Grow the app to more languages by adding a code here + a
+  // `src/locales/<code>.ts`.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+}

package/templates/apps/frontend-ssr/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@voltro/cli": "0.1.0",
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/i18n": "0.1.0",
+    "@voltro/ui-shadcn": "0.1.0",
+    "@voltro/web": "0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/frontend-ssr/src/globals.css

@@ -0,0 +1,67 @@
+/* Self-contained styles — plain CSS, no Tailwind / kit dependency. */
+
+:root {
+  --bg: #ffffff;
+  --fg: #18181b;
+  --muted: #71717a;
+  --accent: #ea580c;
+  --border: #e4e4e7;
+  --code-bg: #f4f4f5;
+}
+
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #a1a1aa;
+  --accent: #fb923c;
+  --border: #27272a;
+  --code-bg: #18181b;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; min-height: 100vh; }
+
+body {
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+main { max-width: 40rem; margin: 0 auto; padding: 2rem 1.25rem 5rem; }
+
+nav.top {
+  display: flex;
+  gap: 1rem;
+  padding: 1rem 1.25rem;
+  border-bottom: 1px solid var(--border);
+}
+nav.top a { color: var(--muted); text-decoration: none; font-size: 0.95rem; }
+nav.top a:hover { color: var(--accent); }
+
+h1 { font-size: 1.6rem; margin: 0 0 0.25rem; }
+.lead { color: var(--muted); margin: 0 0 1.5rem; }
+
+.fields { list-style: none; padding: 0; margin: 1.5rem 0; }
+.fields li { display: flex; justify-content: space-between; padding: 0.6rem 0; border-bottom: 1px solid var(--border); gap: 1rem; }
+.fields .k { color: var(--muted); }
+.fields .v { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; text-align: right; word-break: break-all; }
+
+code { background: var(--code-bg); padding: 0.1rem 0.35rem; border-radius: 5px; font-size: 0.9em; }
+
+.note {
+  margin-top: 2rem;
+  padding: 1rem;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+.badge {
+  display: inline-block;
+  padding: 0.15rem 0.5rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  background: var(--accent);
+  color: #fff;
+}

package/templates/apps/frontend-ssr/src/locales/de.ts

@@ -0,0 +1,41 @@
+// German catalog. Mirrors every key in `en.ts` — `defineLocale<typeof en>()`
+// fails the build if a key is missing or misspelled. Translate the prose only;
+// keep ICU placeholders and rich tags (`<code>`) identical to `en.ts`.
+
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.ssr.title':       '{{capProjectName}} — SSR (frisch pro Anfrage)',
+  'meta.ssr.description': 'Bei jeder Anfrage serverseitig gerendert.',
+  'meta.isr.title':       '{{capProjectName}} — ISR (gecacht + revalidiert)',
+  'meta.isr.description': 'Gecachtes HTML, in einem Zeitfenster revalidiert.',
+  'meta.swr.title':       '{{capProjectName}} — stale-while-revalidate',
+  'meta.swr.description': 'Sofort veraltet ausliefern, im Hintergrund aktualisieren.',
+
+  'nav.ssr':    '/ (ssr)',
+  'nav.isr':    '/feed (isr)',
+  'nav.swr':    '/feed-swr (isr + swr)',
+  'lang.label': 'Sprache',
+
+  'field.renderedAt': 'Gerendert am',
+  'field.nonce':      'Nonce',
+
+  'ssr.badge':                'renderMode: ssr',
+  'ssr.heading':              'Frisch bei jeder Anfrage',
+  'ssr.lead':                 'Aktualisieren — Zeitstempel und Nonce ändern sich jedes Mal.',
+  'ssr.field.acceptLanguage': 'Accept-Language',
+  'ssr.field.themeCookie':    'voltro:theme-Cookie',
+  'ssr.note':                 'SSR-Antworten tragen <code>x-voltro-rendered-by: ssr</code> und werden nie gecacht. Diese Seite braucht eine Laufzeit — liefere sie mit <code>voltro start</code> aus, nicht über ein reines CDN.',
+
+  'isr.badge':        'renderMode: isr · revalidate 10s',
+  'isr.heading':      'Gecacht, dann revalidiert',
+  'isr.lead':         'Zweimal schnell aktualisieren — gleiche Nonce (Cache-HIT). 10s+ warten, aktualisieren — frische Nonce.',
+  'isr.field.tenant': 'Mandant (aus x-tenant)',
+  'isr.note':         'Beobachte die Response-Header: <code>x-voltro-cache: MISS</code> bei der ersten Anfrage (sie wurde gerendert), dann <code>HIT</code> innerhalb des Fensters, dann wieder <code>MISS</code>, nachdem es abgelaufen ist. Mit <code>tenantAware: true</code> enthält der Cache-Schlüssel <code>x-tenant</code>.',
+
+  'swr.badge':   'renderMode: isr · revalidate 5s · swr 30s',
+  'swr.heading': 'Stale-while-revalidate',
+  'swr.lead':    'Zuerst frisch; HIT innerhalb von 5s; STALE (sofort) von 5–35s, während im Hintergrund aktualisiert wird.',
+  'swr.note':    'Der Response-Header verrät, welcher Pfad die Seite ausgeliefert hat: <code>x-voltro-cache: MISS</code> → <code>HIT</code> → <code>STALE</code> (Hintergrund-Aktualisierung) → wieder <code>MISS</code> nach dem SWR-Fenster.',
+})

package/templates/apps/frontend-ssr/src/locales/en.ts

@@ -0,0 +1,54 @@
+// Base catalog — the source of truth for this app's UI strings. Every key here
+// MUST be mirrored in `de.ts` (and any other locale); `defineLocale<typeof en>()`
+// enforces that parity at build time, so a missing translation fails typecheck
+// rather than silently falling back.
+//
+// Messages use ICU syntax: `{name}` placeholders and rich tags like
+// `<code>…</code>` (rendered by passing a matching function to
+// `<T values={{ code: (c) => <code>{c}</code> }} />`).
+
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  // Browser tab titles + descriptions — locale-aware via each page's
+  // `meta({ locale })`. These are plain lookups (not ICU-formatted), so the
+  // `{{capProjectName}}` scaffold token is fine here.
+  'meta.ssr.title':       '{{capProjectName}} — SSR (fresh per request)',
+  'meta.ssr.description': 'Server-rendered on every request.',
+  'meta.isr.title':       '{{capProjectName}} — ISR (cached + revalidated)',
+  'meta.isr.description': 'Cached HTML, revalidated on a window.',
+  'meta.swr.title':       '{{capProjectName}} — stale-while-revalidate',
+  'meta.swr.description': 'Serve stale instantly, refresh in the background.',
+
+  // ---- Layout shell (pages/layout.tsx) ----
+  // Route + render-mode labels — technical tokens, identical across locales.
+  'nav.ssr':    '/ (ssr)',
+  'nav.isr':    '/feed (isr)',
+  'nav.swr':    '/feed-swr (isr + swr)',
+  'lang.label': 'Language',
+
+  // ---- Shared field labels ----
+  'field.renderedAt': 'Rendered at',
+  'field.nonce':      'Nonce',
+
+  // ---- SSR page (pages/index.tsx) ----
+  'ssr.badge':                'renderMode: ssr',
+  'ssr.heading':              'Fresh on every request',
+  'ssr.lead':                 'Refresh — the timestamp and nonce change each time.',
+  'ssr.field.acceptLanguage': 'Accept-Language',
+  'ssr.field.themeCookie':    'voltro:theme cookie',
+  'ssr.note':                 'SSR responses carry <code>x-voltro-rendered-by: ssr</code> and are never cached. This page needs a runtime — serve it with <code>voltro start</code>, not a bare CDN.',
+
+  // ---- ISR page (pages/feed.tsx) ----
+  'isr.badge':        'renderMode: isr · revalidate 10s',
+  'isr.heading':      'Cached, then revalidated',
+  'isr.lead':         'Refresh twice fast — same nonce (cache HIT). Wait 10s+, refresh — fresh nonce.',
+  'isr.field.tenant': 'Tenant (from x-tenant)',
+  'isr.note':         'Watch the response headers: <code>x-voltro-cache: MISS</code> on the first request (it rendered), then <code>HIT</code> within the window, then <code>MISS</code> again after it expires. With <code>tenantAware: true</code> the cache key includes <code>x-tenant</code>.',
+
+  // ---- ISR + stale-while-revalidate page (pages/feed-swr.tsx) ----
+  'swr.badge':   'renderMode: isr · revalidate 5s · swr 30s',
+  'swr.heading': 'Stale-while-revalidate',
+  'swr.lead':    'Fresh first; HIT within 5s; STALE (instant) from 5–35s while a background refresh runs.',
+  'swr.note':    'The response header tells you which path served the page: <code>x-voltro-cache: MISS</code> → <code>HIT</code> → <code>STALE</code> (background refresh) → <code>MISS</code> again after the SWR window.',
+} as const)

package/templates/apps/frontend-ssr/src/locales/index.ts

@@ -0,0 +1,16 @@
+// Catalog lookup OUTSIDE React — for a page's `meta({ locale })` locale-aware
+// <title> / <meta description>. This app is cookie-i18n (no `/<locale>` URL
+// prefix), so @voltro/web hands `meta` the active locale from the `voltro:lang`
+// cookie. Inside React, use `<T>` / `useT()` via the framework's auto-wired
+// <I18nProvider> instead.
+
+import en from './en'
+import de from './de'
+
+// Both catalogs share `en`'s keys (defineLocale enforces the mirror), so a
+// known-key lookup returns `string` — not `string | undefined` — which is what
+// `PageMeta.title` requires under exactOptionalPropertyTypes.
+export type Messages = Record<keyof typeof en, string>
+
+export const getCatalog = (locale?: string): Messages =>
+  (locale === 'de' ? de : en) as Messages