@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/frontend-portal/src/pages/login/page.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+//
+// The auth form. We assert config + that it renders email/password fields and
+// toggles between sign-in and sign-up. The network submit (CSRF + POST /auth/*)
+// is exercised against a running api by `voltro dev`, not unit-mocked here.
+
+import { afterEach, 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'
+
+const { default: Login, meta, renderMode } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+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 }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('login — config', () => {
+  test('is a static page titled Sign in', () => {
+    expect(renderMode).toBe('static')
+    expect(meta({ locale: 'en' }).title).toBe('Sign in')
+  })
+})
+
+describe('login — form', () => {
+  test('renders email + password inputs and defaults to sign-in', () => {
+    render(createElement(Login))
+    expect(container.querySelector('input[type="email"]')).not.toBeNull()
+    expect(container.querySelector('input[type="password"]')).not.toBeNull()
+    expect(container.querySelector('h1')?.textContent).toBe('Sign in')
+  })
+
+  test('toggling switches to the create-account heading', () => {
+    render(createElement(Login))
+    const toggle = container.querySelector('.link')!
+    act(() => { toggle.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    expect(container.querySelector('h1')?.textContent).toBe('Create your account')
+  })
+})

package/templates/apps/frontend-portal/src/pages/login/page.tsx

@@ -0,0 +1,96 @@
+// Sign in / sign up — URL `/login`. A REAL auth form: it POSTs to the api's
+// `/auth/*` routes (contributed by @voltro/plugin-auth on the sibling api),
+// which set the HttpOnly session cookie. State-changing auth routes are
+// CSRF-protected, so we fetch a token first. On success we do a FULL navigation
+// (`window.location.assign`) rather than a client one, so the dashboard's SSR
+// auth gate re-runs with the freshly-set cookie.
+import type { ReactNode } from 'react'
+import { useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales/index'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.login.title'],
+})
+
+type Mode = 'signIn' | 'signUp'
+
+// One round-trip: get a CSRF token, then POST the credentials with it. Returns
+// true on a 2xx (cookie set), false otherwise.
+async function submitAuth(mode: Mode, email: string, password: string): Promise<boolean> {
+  const csrf = (await fetch('/auth/csrf').then((r) => r.json())) as { csrfToken: string }
+  const path = mode === 'signUp' ? '/auth/sign-up' : '/auth/sign-in'
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-csrf-token': csrf.csrfToken },
+    body: JSON.stringify({ email, password }),
+  })
+  return res.ok
+}
+
+export default function Login(): ReactNode {
+  const [mode, setMode] = useState<Mode>('signIn')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [pending, setPending] = useState(false)
+  const [failed, setFailed] = useState(false)
+  const emailLabel = useT('auth.email')
+  const passwordLabel = useT('auth.password')
+
+  const onSubmit = (e: FormEvent): void => {
+    e.preventDefault()
+    setPending(true)
+    setFailed(false)
+    void submitAuth(mode, email, password)
+      .then((ok) => {
+        if (ok) {
+          const from = new URLSearchParams(window.location.search).get('from') ?? '/'
+          window.location.assign(from)
+        } else {
+          setFailed(true)
+          setPending(false)
+        }
+      })
+      .catch(() => {
+        setFailed(true)
+        setPending(false)
+      })
+  }
+
+  return (
+    <section className="hero">
+      <h1><T id={mode === 'signUp' ? 'auth.signUp.heading' : 'auth.signIn.heading'} /></h1>
+      <form className="auth-form" onSubmit={onSubmit}>
+        <label>
+          <span><T id="auth.email" /></span>
+          <input
+            type="email" required aria-label={emailLabel} value={email}
+            onChange={(e) => setEmail(e.target.value)}
+          />
+        </label>
+        <label>
+          <span><T id="auth.password" /></span>
+          <input
+            type="password" required aria-label={passwordLabel} value={password}
+            onChange={(e) => setPassword(e.target.value)}
+          />
+        </label>
+        {failed ? <p className="error-text"><T id="auth.error" /></p> : null}
+        <button type="submit" className="btn" disabled={pending}>
+          <T id={pending ? 'auth.pending' : mode === 'signUp' ? 'auth.signUp.submit' : 'auth.signIn.submit'} />
+        </button>
+      </form>
+      <p style={{ marginTop: '1rem' }}>
+        <button
+          type="button" className="link"
+          onClick={() => { setMode((m) => (m === 'signIn' ? 'signUp' : 'signIn')); setFailed(false) }}
+        >
+          <T id={mode === 'signIn' ? 'auth.toggle.toSignUp' : 'auth.toggle.toSignIn'} />
+        </button>
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-portal",
+  "kind": "web",
+  "summary": "A lean customer billing + account portal over the api-saas-starter backend: an SSR auth gate (session.me), an overview, a billing page (plan + payment method via billing.portalUrl + plan change via billing.previewChange/changePlan), a paginated invoice list (billing.invoices → provider hostedUrl/pdfUrl), an API-keys page over the framework's /v1/api-keys REST surface (degrades cleanly when not enabled), and a profile page. Bilingual (en/de).",
+  "tags": ["web", "frontend", "portal", "billing", "invoices", "api-keys", "account", "ssr"]
+}

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

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,73 @@
+# {{capProjectName}} {{capAppName}} — the SaaS dashboard
+
+The frontend that closes the **signup → paywall → app** loop, consuming the
+`api-saas-starter` api. Bilingual (en/de), auth-gated, live.
+
+Scaffold both halves together:
+
+```bash
+voltro init my-saas --api=api-saas-starter --web=frontend-saas
+voltro dev            # api on :4000, this app on its configured port
+```
+
+## The loop, as pages
+
+| URL | What it does |
+|---|---|
+| `/` | Marketing landing (static, zero-JS) |
+| `/login` | Sign-in / sign-up form → POST `/auth/*` (CSRF handled), sets the session cookie |
+| `/dashboard` | **Gate** (SSR loader asks `session.me`, redirects anonymous → /login) + live projects list; creating the 4th trips the **paywall** |
+| `/dashboard/billing` | Live `billing.subscription`; **upgrade** via `billing.startCheckout`, **add seats** via `billing.changeSeats` |
+| `/dashboard/team` | Live `invites.list`; **invite** via `invites.create` (spends a seat) |
+
+## How the pieces connect
+
+- **Auth gate** — `dashboard/layout.tsx` exports a `loader`. Server-side it calls
+  the api's `session.me` (forwarding the session cookie) and throws
+  `RedirectError('/login')` for an anonymous caller. The pages under it are
+  `renderMode: 'ssr'` so the gate runs per request.
+- **Live reads** — `useSubscription('app', 'projects.list' | 'invites.list' |
+  'billing.subscription')`. First paint is server-rendered; the WebSocket
+  upgrades it live.
+- **The paywall** — `projects.create` / `invites.create` are entitlement-gated
+  on the api. When quota runs out the mutation rejects with a typed
+  `EntitlementExceeded`; the page branches on `isEntitlementExceeded(err)` (see
+  `src/lib/api.ts`) and shows the upgrade CTA — never a raw error string.
+- **Checkout + seats** — `useAction('app', 'billing.startCheckout' |
+  'billing.changeSeats')`. Under `voltro dev` the `mock` billing provider returns
+  a dev checkout URL; swap the api to `provider: 'stripe'` for real Stripe.
+
+## i18n
+
+Cookie-driven (no `/<locale>` URL prefix): `<LocaleSwitcher>` writes `voltro:locale`
+and reloads. Every string is a key in `src/locales/en.ts`, mirrored in `de.ts`
+(`defineLocale<typeof en>()` fails the build on a missing key). Add a language
+with a new code in `app.config.ts` + a `src/locales/<code>.ts`.
+
+## Files
+
+```
+src/pages/
+  (marketing)/            silent route group → `/` and `/login`
+    page.tsx              landing (static)
+    login/page.tsx        real auth form → /auth/*
+  dashboard/
+    layout.tsx            SSR auth gate (session.me) + sidebar shell
+    page.tsx              projects list + create + PAYWALL branch
+    billing/page.tsx      subscription + upgrade (checkout) + seats
+    team/page.tsx         invites list + create
+    error.tsx / not-found.tsx
+src/lib/api.ts            local row types + isEntitlementExceeded()
+src/locales/{en,de}.ts    bilingual catalogs
+```
+
+## Anti-patterns
+
+- **String-matching the paywall.** Branch on the typed `_tag ===
+  'EntitlementExceeded'` (`isEntitlementExceeded`), not on a message — messages
+  are localized and change.
+- **A `static` gated page.** The auth gate must run per request; a `static` page
+  can't redirect per-visitor and the build rejects a `RedirectError` there. Keep
+  the dashboard pages `renderMode: 'ssr'`.
+- **Putting a secret in this app's env.** The browser bundle is public. Secrets
+  live on the api.

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

@@ -0,0 +1,46 @@
+// Web app for the {{projectName}} project — the SaaS DASHBOARD that closes the
+// signup → paywall → app loop against the sibling `api-saas-starter` api.
+//
+// Two areas:
+//   - Public pages in a SILENT route group `src/pages/(marketing)/` — `/` and
+//     `/login` (the parens organise files + scope a layout WITHOUT adding a URL
+//     segment).
+//   - The authed app under `src/pages/dashboard/`. Its `layout.tsx` loader is
+//     the auth gate: server-side it asks the api's `session.me` and throws
+//     RedirectError to /login for an anonymous visitor. Those pages are
+//     `renderMode: 'ssr'` so the gate runs per request.
+//
+// The pages read the api live with `useSubscription` and write with
+// `useMutation` / `useAction`; the auth forms POST to the api's `/auth/*`.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Public, build-time env (baked into the bundle; read via `publicEnv`).
+// Never a secret here — a secret belongs on the api, not the browser bundle.
+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}},
+  // Follow the visitor's OS theme, set before first paint (no flash).
+  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 too). The <LocaleSwitcher> writes the
+  // `voltro:locale` cookie + reloads. Add a code + a `src/locales/<code>.ts` to
+  // grow the app to more languages.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  // The api this dashboard consumes. The NAME ('app') is the lookup key the
+  // hooks + the loader's `query` use: `useSubscription('app', 'projects.list')`,
+  // `useMutation('app', 'projects.create')`, `query('session.me', {})`. Its
+  // port is auto-discovered from the api's own app.config.ts, and codegen pulls
+  // its typed rpc surface (including the plugins' `billing.*` / `/auth`).
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

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

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@{{projectName}}/api": "0.30.0",
+    "@voltro/cli": "0.30.0",
+    "@voltro/client": "0.30.0",
+    "@voltro/env": "0.30.0",
+    "@voltro/i18n": "0.30.0",
+    "@voltro/ui-shadcn": "0.30.0",
+    "@voltro/web": "0.30.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@voltro/devtools": "0.30.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/frontend-saas/src/config.ts

@@ -0,0 +1,8 @@
+// The brand name shown in the marketing header + dashboard sidebar.
+//
+// A plain constant — not `publicEnv` — so the template typechecks BEFORE
+// `voltro dev` generates the env types. `VOLTRO_PUBLIC_APP_NAME` is still
+// declared in app.config.ts (validated + in the env manifest); to read it typed
+// instead, after one `voltro dev` swap this for
+// `publicEnv.VOLTRO_PUBLIC_APP_NAME` from '@voltro/env/public'.
+export const APP_NAME = '{{capProjectName}}'

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

@@ -0,0 +1,85 @@
+/* Plain CSS — no Tailwind, so there's no @source scanner to configure. */
+:root {
+  --bg: #ffffff;
+  --fg: #0a0a0a;
+  --muted: #6b7280;
+  --accent: #4f46e5;
+  --danger: #dc2626;
+  --border: #e5e7eb;
+  --panel: #f9fafb;
+}
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #9ca3af;
+  --accent: #818cf8;
+  --danger: #f87171;
+  --border: #1f2937;
+  --panel: #111827;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  line-height: 1.55;
+}
+a { color: inherit; }
+.muted { color: var(--muted); }
+.spacer { flex: 1; }
+
+/* Buttons + inputs */
+.btn {
+  display: inline-block; cursor: pointer; border: 0; border-radius: 8px;
+  background: var(--accent); color: #fff; padding: 0.55rem 1rem;
+  font: inherit; font-weight: 600; text-decoration: none;
+}
+.btn:disabled { opacity: 0.6; cursor: default; }
+.btn.ghost { background: transparent; color: var(--accent); border: 1px solid var(--border); }
+.link { background: none; border: 0; color: var(--accent); cursor: pointer; font: inherit; padding: 0; }
+input {
+  font: inherit; padding: 0.5rem 0.65rem; border: 1px solid var(--border);
+  border-radius: 8px; background: var(--bg); color: var(--fg); min-width: 0;
+}
+.error-text { color: var(--danger); }
+
+/* Marketing */
+.marketing header {
+  display: flex; align-items: center; gap: 1rem;
+  padding: 1rem 1.5rem; border-bottom: 1px solid var(--border);
+}
+.marketing .brand { font-weight: 700; text-decoration: none; }
+.hero { max-width: 40rem; margin: 0 auto; padding: 3rem 1.5rem; }
+.hero h1 { margin: 0 0 0.75rem; }
+.auth-form { display: flex; flex-direction: column; gap: 0.85rem; max-width: 22rem; margin-top: 1.25rem; }
+.auth-form label { display: flex; flex-direction: column; gap: 0.25rem; font-size: 0.9rem; }
+
+/* Dashboard shell */
+.dash { display: grid; grid-template-columns: 15rem 1fr; min-height: 100vh; }
+.dash aside { border-right: 1px solid var(--border); padding: 1.25rem; background: var(--panel); }
+.dash aside .brand { font-weight: 700; margin-bottom: 1rem; }
+.dash nav { display: flex; flex-direction: column; gap: 0.5rem; }
+.dash nav a { text-decoration: none; color: var(--muted); padding: 0.35rem 0; }
+.dash nav a[aria-current="page"] { color: var(--fg); font-weight: 600; }
+.dash main { padding: 1.5rem 2rem; }
+.topbar { display: flex; align-items: center; margin-bottom: 1rem; }
+@media (max-width: 40rem) { .dash { grid-template-columns: 1fr; } .dash aside { border-right: 0; border-bottom: 1px solid var(--border); } }
+
+/* Bits */
+.row { display: flex; gap: 0.6rem; align-items: center; flex-wrap: wrap; margin-top: 0.5rem; }
+.empty { color: var(--muted); margin-top: 1.5rem; }
+.cards { list-style: none; padding: 0; margin: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr)); gap: 0.75rem; }
+.card { border: 1px solid var(--border); border-radius: 10px; padding: 0.9rem 1rem; background: var(--panel); }
+.card .value { font-weight: 600; }
+.card .label { color: var(--muted); font-size: 0.85rem; margin-top: 0.2rem; }
+.paywall { border: 1px solid var(--accent); border-radius: 12px; padding: 1rem 1.25rem; margin-top: 1.25rem; background: color-mix(in oklab, var(--accent) 8%, transparent); }
+.paywall p { margin: 0.35rem 0 0.75rem; }
+.facts { display: grid; grid-template-columns: max-content 1fr; gap: 0.4rem 1.5rem; margin-top: 1rem; }
+.facts dt { color: var(--muted); }
+.facts dd { margin: 0; font-weight: 600; }
+.rows { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 0.4rem; }
+.rows li { display: flex; justify-content: space-between; align-items: center; border: 1px solid var(--border); border-radius: 8px; padding: 0.6rem 0.9rem; background: var(--panel); }
+.tag { font-size: 0.8rem; color: var(--muted); border: 1px solid var(--border); border-radius: 999px; padding: 0.05rem 0.55rem; }
+code { background: color-mix(in oklab, var(--fg) 8%, transparent); padding: 0.1em 0.35em; border-radius: 4px; }

package/templates/apps/frontend-saas/src/globals.d.ts

@@ -0,0 +1,6 @@
+// Ambient declarations.
+//
+// `declare module '*.css'`: TypeScript with `moduleResolution: Bundler` rejects
+// a bare `import './globals.css'` unless the asset module is declared. Vite
+// resolves it at build time; the declaration is type-only.
+declare module '*.css'

package/templates/apps/frontend-saas/src/lib/api.ts

@@ -0,0 +1,47 @@
+// The row + payload shapes this dashboard reads off the api, kept LOCAL so the
+// pages are self-contained. They mirror the api's descriptor outputs
+// (`projects.list`, `invites.list`, `billing.subscription`); you can also
+// `import type` them from the api package — a type-only cross-app import is
+// browser-safe.
+
+export interface Project {
+  readonly id: string
+  readonly name: string
+  readonly tenantId: string
+  readonly createdAt: string | Date
+}
+
+export interface Invite {
+  readonly id: string
+  readonly email: string
+  readonly status: string
+  readonly tenantId: string
+  readonly createdAt: string | Date
+}
+
+// `billing.subscription` streams `{ subscription: … | null }` — null before the
+// tenant has any subscription row (they're on the implicit free plan).
+export interface SubscriptionState {
+  readonly subscription: {
+    readonly plan: string
+    readonly status: string
+    readonly quantity: number
+    readonly currentPeriodEnd: string | null
+    readonly cancelAt: string | null
+  } | null
+}
+
+// The caller's resolved identity, from `session.me`. The SSR gate reads it.
+export interface Identity {
+  readonly type: string
+  readonly id: string | null
+  readonly tenantId: string | null
+}
+
+// The billing plugin merges a typed `EntitlementExceeded` into the wire-error
+// union of any entitlement-gated mutation (projects.create / invites.create).
+// This is how the paywall is detected — NOT by string-matching a message.
+export const isEntitlementExceeded = (error: unknown): boolean =>
+  typeof error === 'object' &&
+  error !== null &&
+  (error as { _tag?: unknown })._tag === 'EntitlementExceeded'

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

@@ -0,0 +1,72 @@
+// 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 (`{when}`) and rich tags (`<code>`) identical to en.ts.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.landing.title':       'Willkommen',
+  'meta.landing.description': 'Ein vollständiger Voltro-SaaS-Starter — Auth, Plan-Paywall, Checkout, Sitze und Einladungen, durchgängig verdrahtet.',
+  'meta.login.title':         'Anmelden',
+  'meta.overview.title':      'Projekte',
+  'meta.billing.title':       'Abrechnung',
+  'meta.team.title':          'Team',
+
+  'nav.dashboard':   'Dashboard',
+  'nav.signIn':      'Anmelden',
+  'lang.label':      'Sprache',
+  'landing.heading': 'Liefere dein SaaS, nicht seine Rohrleitungen.',
+  'landing.body':    'Registrieren, in der App landen, an die Plan-Paywall stoßen, upgraden, Teammitglied einladen — der ganze Ablauf funktioniert bereits. Auth, Billing-Entitlements und Sitze sind mit dem <code>api-saas-starter</code>-Backend verdrahtet.',
+  'landing.cta':     'Loslegen →',
+
+  'auth.signIn.heading':  'Anmelden',
+  'auth.signUp.heading':  'Konto erstellen',
+  'auth.email':           'E-Mail',
+  'auth.password':        'Passwort',
+  'auth.signIn.submit':   'Anmelden',
+  'auth.signUp.submit':   'Konto erstellen',
+  'auth.toggle.toSignUp': 'Kein Konto? Erstelle eins',
+  'auth.toggle.toSignIn': 'Konto vorhanden? Anmelden',
+  'auth.pending':         'Bitte warten…',
+  'auth.error':           'Das hat nicht geklappt. Prüfe deine Angaben und versuche es erneut.',
+
+  'dash.nav.projects':   'Projekte',
+  'dash.nav.billing':    'Abrechnung',
+  'dash.nav.team':       'Team',
+  'dash.nav.backToSite': '← Zurück zur Seite',
+
+  'projects.heading':       'Projekte',
+  'projects.new.placeholder': 'Name des neuen Projekts',
+  'projects.new.submit':    'Projekt erstellen',
+  'projects.empty':         'Noch keine Projekte — erstelle oben dein erstes.',
+  'projects.created':       'Erstellt {when}',
+  'projects.paywall.title': 'Du hast dein Planlimit erreicht',
+  'projects.paywall.body':  'Der kostenlose Plan umfasst 3 Projekte. Upgrade auf Pro für unbegrenzte Projekte.',
+  'projects.paywall.cta':   'Pläne ansehen →',
+
+  'billing.heading':         'Abrechnung',
+  'billing.plan.label':      'Aktueller Plan',
+  'billing.plan.free':       'Kostenlos',
+  'billing.status.label':    'Status',
+  'billing.seats.label':     'Sitze',
+  'billing.upgrade.title':   'Upgrade auf Pro',
+  'billing.upgrade.body':    'Unbegrenzte Projekte und bis zu 10 Sitze.',
+  'billing.upgrade.cta':     'Upgraden →',
+  'billing.seats.add':       'Sitz hinzufügen',
+  'billing.pending':         'Wird ausgeführt…',
+
+  'team.heading':          'Team',
+  'team.invite.placeholder': 'kollege@example.com',
+  'team.invite.submit':    'Einladung senden',
+  'team.empty':            'Noch keine Einladungen.',
+  'team.paywall':          'Keine Sitze mehr frei. Füge auf der Abrechnungsseite einen Sitz hinzu und lade erneut ein.',
+  'team.status.pending':   'ausstehend',
+  'team.status.accepted':  'angenommen',
+  'team.status.revoked':   'widerrufen',
+
+  'error.heading':    'Etwas ist schiefgelaufen',
+  'error.retry':      'Erneut versuchen',
+  'notFound.heading': 'Nicht gefunden',
+  'notFound.body':    'Diese Seite existiert nicht.',
+  'notFound.back':    '← Zurück zu den Projekten',
+})

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

@@ -0,0 +1,81 @@
+// Base catalog — the source of truth for this app's UI strings. Every key here
+// MUST be mirrored in `de.ts`; `defineLocale<typeof en>()` enforces that parity
+// at build time, so a missing translation fails typecheck rather than silently
+// falling back. Messages use ICU: `{name}` placeholders + rich `<code>…</code>`
+// tags rendered by passing a matching function to `<T values={{ … }} />`.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  // Browser tab titles — locale-aware via each page's `meta({ locale })`.
+  'meta.landing.title':       'Welcome',
+  'meta.landing.description': 'A full Voltro SaaS starter — auth, a plan paywall, checkout, seats and invites, wired end to end.',
+  'meta.login.title':         'Sign in',
+  'meta.overview.title':      'Projects',
+  'meta.billing.title':       'Billing',
+  'meta.team.title':          'Team',
+
+  // ---- Marketing chrome + landing ----
+  'nav.dashboard':   'Dashboard',
+  'nav.signIn':      'Sign in',
+  'lang.label':      'Language',
+  'landing.heading': 'Ship your SaaS, not its plumbing.',
+  'landing.body':    'Sign up, land in the app, hit the plan paywall, upgrade, invite a teammate — the whole loop already works. Auth, billing entitlements and seats are wired to the <code>api-saas-starter</code> backend.',
+  'landing.cta':     'Get started →',
+
+  // ---- Auth form ((marketing)/login) ----
+  'auth.signIn.heading':  'Sign in',
+  'auth.signUp.heading':  'Create your account',
+  'auth.email':           'Email',
+  'auth.password':        'Password',
+  'auth.signIn.submit':   'Sign in',
+  'auth.signUp.submit':   'Create account',
+  'auth.toggle.toSignUp': 'No account? Create one',
+  'auth.toggle.toSignIn': 'Have an account? Sign in',
+  'auth.pending':         'Please wait…',
+  'auth.error':           'That didn’t work. Check your details and try again.',
+
+  // ---- Dashboard shell ----
+  'dash.nav.projects':   'Projects',
+  'dash.nav.billing':    'Billing',
+  'dash.nav.team':       'Team',
+  'dash.nav.backToSite': '← Back to site',
+
+  // ---- Projects page ----
+  'projects.heading':       'Projects',
+  'projects.new.placeholder': 'New project name',
+  'projects.new.submit':    'Create project',
+  'projects.empty':         'No projects yet — create your first one above.',
+  'projects.created':       'Created {when}',
+  'projects.paywall.title': 'You’ve hit your plan limit',
+  'projects.paywall.body':  'The free plan includes 3 projects. Upgrade to Pro for unlimited projects.',
+  'projects.paywall.cta':   'See plans →',
+
+  // ---- Billing page ----
+  'billing.heading':         'Billing',
+  'billing.plan.label':      'Current plan',
+  'billing.plan.free':       'Free',
+  'billing.status.label':    'Status',
+  'billing.seats.label':     'Seats',
+  'billing.upgrade.title':   'Upgrade to Pro',
+  'billing.upgrade.body':    'Unlimited projects and up to 10 seats.',
+  'billing.upgrade.cta':     'Upgrade →',
+  'billing.seats.add':       'Add a seat',
+  'billing.pending':         'Working…',
+
+  // ---- Team page ----
+  'team.heading':          'Team',
+  'team.invite.placeholder': 'teammate@example.com',
+  'team.invite.submit':    'Send invite',
+  'team.empty':            'No invites yet.',
+  'team.paywall':          'You’re out of seats. Add a seat on the Billing page, then invite again.',
+  'team.status.pending':   'pending',
+  'team.status.accepted':  'accepted',
+  'team.status.revoked':   'revoked',
+
+  // ---- Scoped fallbacks ----
+  'error.heading':    'Something went wrong',
+  'error.retry':      'Try again',
+  'notFound.heading': 'Not found',
+  'notFound.body':    'That page doesn’t exist.',
+  'notFound.back':    '← Back to projects',
+} as const)

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

@@ -0,0 +1,14 @@
+// Catalog lookup OUTSIDE React — for a page's `meta({ locale })` locale-aware
+// <title>. This app is cookie-i18n (no `/<locale>` URL prefix), so @voltro/web
+// hands `meta` the active locale from the `voltro:locale` 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` — 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