@voltro/cli 0.27.0 → 0.29.0

package/templates/apps/frontend-portal/src/pages/(portal)/billing/page.tsx

@@ -0,0 +1,97 @@
+// Billing — URL `/billing`. The current plan (live from `billing.subscription`),
+// a card-management button that redirects to the PROVIDER's hosted portal
+// (`billing.portalUrl`), and a plan change that QUOTES the provider's prorated
+// settlement first (`billing.previewChange`) before applying it
+// (`billing.changePlan`) — never a locally-estimated figure.
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useSubscription, useAction } from '@voltro/client'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import { formatMoney, type ChangePreview, type SubscriptionState } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.billing.title'],
+})
+
+// The plan a free tenant upgrades to — matches api-saas-starter's `plans`.
+const UPGRADE_PLAN = 'pro'
+
+export default function Billing(): ReactNode {
+  const locale = useLocale()
+  const { data } = useSubscription<SubscriptionState>('app', 'billing.subscription')
+  const portal = useAction<{ returnUrl: string }, { url: string }>('app', 'billing.portalUrl')
+  const preview = useAction<{ plan?: string; quantity?: number }, ChangePreview>('app', 'billing.previewChange')
+  const change = useAction<{ plan: string }, ChangePreview>('app', 'billing.changePlan')
+
+  const [quote, setQuote] = useState<ChangePreview | null>(null)
+  const [changed, setChanged] = useState(false)
+  const sub = data?.subscription ?? null
+  const freeLabel = useT('billing.plan.free')
+  const busy = portal.pending || preview.pending || change.pending
+
+  const onManageCard = (): void => {
+    const here = typeof window === 'undefined' ? '/billing' : window.location.href
+    void portal.run({ returnUrl: here })
+      .then((r) => { if (r && typeof window !== 'undefined') window.location.assign(r.url) })
+      .catch(() => { /* surfaced via portal.error */ })
+  }
+
+  const onPreview = (): void => {
+    setChanged(false)
+    void preview.run({ plan: UPGRADE_PLAN }).then((q) => setQuote(q)).catch(() => setQuote(null))
+  }
+
+  const onConfirm = (): void => {
+    void change.run({ plan: UPGRADE_PLAN }).then(() => { setChanged(true); setQuote(null) }).catch(() => { /* change.error */ })
+  }
+
+  return (
+    <section>
+      <h1><T id="billing.heading" /></h1>
+
+      <dl className="facts">
+        <dt><T id="billing.plan.label" /></dt>
+        <dd>{sub?.plan ?? freeLabel}</dd>
+        <dt><T id="billing.status.label" /></dt>
+        <dd>{sub?.status ?? '—'}</dd>
+        <dt><T id="billing.seats.label" /></dt>
+        <dd>{sub?.quantity ?? 1}</dd>
+      </dl>
+
+      <div className="row" style={{ marginTop: '1.25rem' }}>
+        <button type="button" className="btn ghost" disabled={busy} onClick={onManageCard}>
+          <T id="billing.card.manage" />
+        </button>
+      </div>
+
+      <div className="paywall" style={{ marginTop: '1.5rem' }}>
+        <strong><T id="billing.change.title" /></strong>
+        <p className="muted"><T id="billing.change.body" /></p>
+        {quote ? (
+          <p role="status">
+            <T
+              id="billing.change.quote"
+              values={{ amount: formatMoney(Math.abs(quote.prorationMinor), quote.currency, locale) }}
+            />
+          </p>
+        ) : null}
+        {changed ? <p className="ok" role="status"><T id="billing.change.done" /></p> : null}
+        <div className="row">
+          {quote ? (
+            <button type="button" className="btn" disabled={busy} onClick={onConfirm}>
+              <T id={change.pending ? 'billing.pending' : 'billing.change.confirm'} />
+            </button>
+          ) : (
+            <button type="button" className="btn" disabled={busy} onClick={onPreview}>
+              <T id={preview.pending ? 'billing.pending' : 'billing.change.preview'} />
+            </button>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/error.tsx

@@ -0,0 +1,19 @@
+// Error boundary scoped to the portal subtree. A render error (or a loader
+// rejection that ISN'T a RedirectError / NotFoundError) bubbles here.
+import type { ReactNode } from 'react'
+import type { ErrorBoundaryProps } from '@voltro/web'
+import { T } from '@voltro/i18n'
+
+export default function PortalError({ error, reset }: ErrorBoundaryProps): ReactNode {
+  return (
+    <div className="dash">
+      <main>
+        <h1><T id="error.heading" /></h1>
+        <p className="muted">{String(error)}</p>
+        <p style={{ marginTop: '1rem' }}>
+          <button type="button" className="btn" onClick={reset}><T id="error.retry" /></button>
+        </p>
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/invoices/page.tsx

@@ -0,0 +1,45 @@
+// Invoices — URL `/invoices`. Lists the tenant's invoice history live from
+// `billing.invoices`. Each row's amount/status is shown; "View" / "PDF" link OUT
+// to the provider's own hosted pages (`hostedUrl` / `pdfUrl`) — the portal never
+// renders an invoice document itself.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+import { T, useLocale } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import { formatMoney, type Invoice } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.invoices.title'],
+})
+
+export default function Invoices(): ReactNode {
+  const locale = useLocale()
+  const { data } = useSubscription<{ invoices: ReadonlyArray<Invoice> }>('app', 'billing.invoices')
+  const invoices = data?.invoices ?? []
+
+  return (
+    <section>
+      <h1><T id="invoices.heading" /></h1>
+      {invoices.length === 0 ? (
+        <p className="empty"><T id="invoices.empty" /></p>
+      ) : (
+        <ul className="rows" style={{ marginTop: '1.25rem' }}>
+          {invoices.map((inv) => (
+            <li key={inv.providerInvoiceId}>
+              <span className="grow">
+                {inv.createdAt ? new Date(inv.createdAt).toLocaleDateString() : '—'}
+              </span>
+              <span>{formatMoney(inv.amountMinor, inv.currency, locale)}</span>
+              <span className="tag">{inv.status}</span>
+              {inv.hostedUrl ? <a href={inv.hostedUrl} target="_blank" rel="noopener noreferrer"><T id="invoices.view" /></a> : null}
+              {inv.pdfUrl ? <a href={inv.pdfUrl} target="_blank" rel="noopener noreferrer"><T id="invoices.pdf" /></a> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/layout.test.tsx

@@ -0,0 +1,31 @@
+// The portal auth GATE, tested at the loader. Server-side (a `query` fn is
+// present) it asks the api's `session.me`: an anonymous identity must throw
+// RedirectError to /login; a `user` identity resolves with the tenant. On a
+// client navigation (`query` undefined) it resolves permissively.
+
+import { describe, expect, test, vi } from 'vitest'
+import { RedirectError } from '@voltro/web'
+import { loader } from './layout'
+import type { Identity } from '../../lib/api'
+
+const queryReturning = (identity: Identity) =>
+  vi.fn(async (_tag: string, _input: unknown) => identity as unknown)
+
+describe('portal gate — loader', () => {
+  test('redirects an anonymous caller to /login', async () => {
+    const query = queryReturning({ type: 'anonymous', id: null, tenantId: null })
+    await expect(loader({ query } as never)).rejects.toBeInstanceOf(RedirectError)
+    expect(query).toHaveBeenCalledWith('session.me', {})
+  })
+
+  test('lets a signed-in user through and returns the tenant', async () => {
+    const query = queryReturning({ type: 'user', id: 'u_1', tenantId: 'acme' })
+    const data = await loader({ query } as never)
+    expect(data).toEqual({ tenantId: 'acme' })
+  })
+
+  test('client navigation (no server query fn) resolves without re-gating', async () => {
+    const data = await loader({ query: undefined } as never)
+    expect(data).toEqual({ tenantId: null })
+  })
+})

package/templates/apps/frontend-portal/src/pages/(portal)/layout.tsx

@@ -0,0 +1,63 @@
+// The portal shell — and the AUTH GATE. This layout wraps every page in the
+// silent `(portal)` group, and its `loader` runs server-side BEFORE the pages
+// render: it asks the api's `session.me` and throws RedirectError to /login for
+// anyone not signed in. The pages under here are `renderMode: 'ssr'` precisely so
+// this runs per request.
+import type { ReactNode } from 'react'
+import { RedirectError, useLoaderData, useLocation, type LoaderFn } from '@voltro/web'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../../config'
+import type { Identity } from '../../lib/api'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+interface PortalData {
+  readonly tenantId: string | null
+}
+
+export const loader: LoaderFn<PortalData> = async ({ query }) => {
+  if (query) {
+    const me = await query<Identity>('session.me', {})
+    if (me.type !== 'user') {
+      throw new RedirectError('/login?from=/')
+    }
+    return { tenantId: me.tenantId }
+  }
+  return { tenantId: null }
+}
+
+export default function PortalLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  useLoaderData<PortalData>()
+  const pathname = useLocation()
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  const navItem = (href: string, label: ReactNode): ReactNode => (
+    <a href={href} aria-current={pathname === href ? 'page' : undefined}>{label}</a>
+  )
+
+  return (
+    <div className="dash">
+      <aside>
+        <div className="brand">{APP_NAME}</div>
+        <nav>
+          {navItem('/', <T id="nav.overview" />)}
+          {navItem('/billing', <T id="nav.billing" />)}
+          {navItem('/invoices', <T id="nav.invoices" />)}
+          {navItem('/api-keys', <T id="nav.apiKeys" />)}
+          {navItem('/profile', <T id="nav.profile" />)}
+        </nav>
+      </aside>
+      <main>
+        <div className="topbar">
+          <span className="spacer" />
+          <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+        </div>
+        {children}
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/not-found.tsx

@@ -0,0 +1,15 @@
+// Scoped 404 for the portal subtree.
+import type { ReactNode } from 'react'
+import { T } from '@voltro/i18n'
+
+export default function PortalNotFound(): ReactNode {
+  return (
+    <div className="dash">
+      <main>
+        <h1><T id="notFound.heading" /></h1>
+        <p className="muted"><T id="notFound.body" /></p>
+        <p style={{ marginTop: '1rem' }}><a href="/"><T id="notFound.back" /></a></p>
+      </main>
+    </div>
+  )
+}

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

@@ -0,0 +1,39 @@
+// Overview — URL `/`. A glance at the account: the current plan (live from
+// `billing.subscription`), renewal date, and quick links into the deeper pages.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+import type { SubscriptionState } from '../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.overview.title'],
+})
+
+export default function Overview(): ReactNode {
+  const { data } = useSubscription<SubscriptionState>('app', 'billing.subscription')
+  const sub = data?.subscription ?? null
+  const freeLabel = useT('billing.plan.free')
+
+  return (
+    <section>
+      <h1><T id="overview.heading" /></h1>
+      <dl className="facts">
+        <dt><T id="billing.plan.label" /></dt>
+        <dd>{sub?.plan ?? freeLabel}</dd>
+        <dt><T id="billing.status.label" /></dt>
+        <dd>{sub?.status ?? '—'}</dd>
+        <dt><T id="overview.renews" /></dt>
+        <dd>{sub?.currentPeriodEnd ? new Date(sub.currentPeriodEnd).toLocaleDateString() : '—'}</dd>
+      </dl>
+      <ul className="cards" style={{ marginTop: '1.5rem' }}>
+        <li className="card"><a href="/billing"><T id="nav.billing" /></a><div className="label"><T id="overview.link.billing" /></div></li>
+        <li className="card"><a href="/invoices"><T id="nav.invoices" /></a><div className="label"><T id="overview.link.invoices" /></div></li>
+        <li className="card"><a href="/api-keys"><T id="nav.apiKeys" /></a><div className="label"><T id="overview.link.apiKeys" /></div></li>
+      </ul>
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/profile/page.tsx

@@ -0,0 +1,79 @@
+// Profile — URL `/profile`. Shows the signed-in identity (from the gate's
+// `session.me`, re-read here), a self-contained password-change (requests a reset
+// link via the api's `/auth/password-reset` route), and sign out. Kept
+// deliberately thin — the portal is account admin, not a settings sprawl.
+import type { ReactNode } from 'react'
+import { useEffect, useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useAction } from '@voltro/client'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import type { Identity } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.profile.title'],
+})
+
+const csrf = async (): Promise<string> => {
+  const body = (await fetch('/auth/csrf').then((r) => r.json())) as { csrfToken?: string }
+  return body.csrfToken ?? ''
+}
+
+export default function Profile(): ReactNode {
+  const me = useAction<Record<string, never>, Identity>('app', 'session.me')
+  const [ident, setIdent] = useState<Identity | null>(null)
+  const [email, setEmail] = useState('')
+  const [sent, setSent] = useState(false)
+  const emailLabel = useT('profile.cp.email')
+
+  useEffect(() => {
+    void me.run({}).then(setIdent).catch(() => setIdent(null))
+  }, []) // read the identity once on mount
+
+  const onChangePassword = (e: FormEvent): void => {
+    e.preventDefault()
+    void csrf()
+      .then((token) =>
+        fetch('/auth/password-reset', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'x-csrf-token': token },
+          body: JSON.stringify({ email }),
+        }),
+      )
+      .finally(() => setSent(true))
+  }
+
+  const signOut = (): void => {
+    void csrf()
+      .then((token) => fetch('/auth/sign-out', { method: 'POST', headers: { 'x-csrf-token': token } }))
+      .finally(() => window.location.assign('/login'))
+  }
+
+  return (
+    <section>
+      <h1><T id="profile.heading" /></h1>
+      <dl className="facts">
+        <dt><T id="profile.id" /></dt>
+        <dd><code>{ident?.id ?? '—'}</code></dd>
+        <dt><T id="profile.tenant" /></dt>
+        <dd><code>{ident?.tenantId ?? '—'}</code></dd>
+      </dl>
+
+      <h2 style={{ marginTop: '1.5rem' }}><T id="profile.cp.heading" /></h2>
+      {sent ? (
+        <p className="ok" role="status"><T id="profile.cp.sent" /></p>
+      ) : (
+        <form className="row" onSubmit={onChangePassword}>
+          <input type="email" required aria-label={emailLabel} placeholder={emailLabel} value={email} onChange={(e) => setEmail(e.target.value)} />
+          <button type="submit" className="btn ghost"><T id="profile.cp.submit" /></button>
+        </form>
+      )}
+
+      <div className="row" style={{ marginTop: '1.5rem' }}>
+        <button type="button" className="btn" onClick={signOut}><T id="profile.signOut" /></button>
+      </div>
+    </section>
+  )
+}

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

@@ -0,0 +1,12 @@
+// Root layout — wraps EVERY page (marketing + dashboard). Thin: it loads the
+// stylesheet and lets each AREA layout ((marketing)/layout.tsx,
+// dashboard/layout.tsx) supply its own chrome. Layouts nest, so a dashboard
+// page is wrapped root → dashboard.
+//
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+import type { ReactNode } from 'react'
+import '../globals.css'
+
+export default function RootLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  return <>{children}</>
+}

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:lang`
+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.