@voltro/cli 0.1.0

package/templates/apps/frontend-dashboard/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-dashboard/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-dashboard/src/globals.css

@@ -0,0 +1,72 @@
+/* Plain CSS — no Tailwind, so there's no @source scanner to configure.
+   Swap in @voltro/ui-shadcn or Tailwind later if you want; see AGENTS.md. */
+:root {
+  --bg: #ffffff;
+  --fg: #0a0a0a;
+  --muted: #6b7280;
+  --accent: #4f46e5;
+  --border: #e5e7eb;
+  --panel: #f9fafb;
+}
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #9ca3af;
+  --accent: #818cf8;
+  --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: var(--accent); }
+
+/* Marketing */
+.marketing { max-width: 44rem; margin: 0 auto; padding: 2.5rem 1.25rem; }
+.marketing header { display: flex; gap: 1rem; align-items: center; margin-bottom: 2rem; }
+.marketing header .brand { font-weight: 700; }
+.marketing header .spacer { flex: 1; }
+.hero h1 { font-size: 2rem; margin: 0 0 0.5rem; }
+.btn {
+  display: inline-block;
+  background: var(--accent);
+  color: #fff;
+  padding: 0.55rem 1rem;
+  border-radius: 8px;
+  border: 0;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  text-decoration: none;
+}
+
+/* Dashboard shell */
+.dash { display: grid; grid-template-columns: 14rem 1fr; min-height: 100vh; }
+.dash aside {
+  border-right: 1px solid var(--border);
+  background: var(--panel);
+  padding: 1.25rem 1rem;
+}
+.dash aside .brand { font-weight: 700; margin-bottom: 1.25rem; }
+.dash nav { display: flex; flex-direction: column; gap: 0.25rem; }
+.dash nav a { color: var(--fg); text-decoration: none; padding: 0.4rem 0.6rem; border-radius: 6px; }
+.dash nav a:hover { background: color-mix(in oklab, var(--fg) 7%, transparent); }
+.dash nav a[aria-current='page'] { background: color-mix(in oklab, var(--accent) 16%, transparent); color: var(--accent); font-weight: 600; }
+.dash main { padding: 1.75rem; }
+.dash .topbar { display: flex; align-items: center; gap: 1rem; margin-bottom: 1.5rem; }
+.dash .topbar .spacer { flex: 1; }
+
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(11rem, 1fr)); gap: 1rem; }
+.card { border: 1px solid var(--border); border-radius: 10px; padding: 1rem; background: var(--panel); }
+.card .label { color: var(--muted); font-size: 0.8rem; }
+.card .value { font-size: 1.6rem; font-weight: 700; }
+
+.muted { color: var(--muted); }
+.skeleton { border: 1px solid var(--border); border-radius: 10px; height: 5rem; background: linear-gradient(90deg, var(--panel), color-mix(in oklab, var(--panel) 60%, var(--bg)), var(--panel)); }
+code { background: color-mix(in oklab, var(--fg) 8%, transparent); padding: 0.1em 0.35em; border-radius: 4px; }

package/templates/apps/frontend-dashboard/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-dashboard/src/lib/auth.ts

@@ -0,0 +1,27 @@
+// The demo auth gate. This is intentionally a COOKIE-ONLY stand-in so the
+// template boots with zero backend — `login` writes the cookie, the
+// dashboard layout loader reads it. Swap `isSignedIn` for a real check
+// (verify a signed session, call your api) when you wire auth for real.
+
+export const SESSION_COOKIE = 'demo_session'
+
+// Browser-safe cookie parse — NO `node:*` import, so it's safe in the page
+// module graph. It runs in BOTH places the gate needs it:
+//   - SSR: the loader's `headers['cookie']` (raw Cookie request header)
+//   - client nav: `document.cookie` (the loader's `headers` is undefined
+//     on the client, so the gate falls back to this)
+export const readCookie = (
+  header: string | null | undefined,
+  name: string,
+): string | undefined => {
+  if (!header) return undefined
+  const match = new RegExp(`(?:^|;\\s*)${name}=([^;]*)`).exec(header)
+  return match ? decodeURIComponent(match[1]!) : undefined
+}
+
+// `headers` is populated server-side (SSR); on the client it's undefined, so
+// fall back to document.cookie. Either way: is there a session cookie?
+export const isSignedIn = (headers: Record<string, string | undefined> | undefined): boolean => {
+  const cookieHeader = headers?.['cookie'] ?? (typeof document === 'undefined' ? '' : document.cookie)
+  return readCookie(cookieHeader, SESSION_COOKIE) !== undefined
+}

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

@@ -0,0 +1,49 @@
+// 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 (`{plan}`) and rich tags (`<code>`, `<dash>`, `<login>`)
+// 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 Voltro-Dashboard-Starter — öffentliche Marketing-Seiten + eine auth-geschützte App-Hülle.',
+  'meta.login.title':         'Anmelden',
+  'meta.overview.title':      'Übersicht',
+  'meta.settings.title':      'Einstellungen',
+
+  'nav.dashboard': 'Dashboard',
+  'nav.signIn':    'Anmelden',
+  'lang.label':    'Sprache',
+
+  'landing.heading': 'Deine App, mit den lästigen Teilen erledigt.',
+  'landing.body':    'Diese Vorlage liefert einen öffentlichen Marketing-Bereich (eine stille <code>(marketing)</code>-Routengruppe) und einen <code>/dashboard</code>-Bereich, der durch einen Layout-Loader geschützt ist — öffne <dash>/dashboard</dash> im abgemeldeten Zustand und du wirst zu <login>/login</login> weitergeleitet.',
+  'landing.cta':     'Anmelden, um fortzufahren →',
+
+  'login.heading': 'Anmelden',
+  'login.body':    'Keine echte Authentifizierung hier — dieser Button setzt lediglich ein Demo-Session-Cookie, damit du siehst, wie das Dashboard-Gate dich durchlässt.',
+  'login.cta':     'Als Demo-Benutzer fortfahren →',
+
+  'dash.planSuffix':     '· Tarif {plan}',
+  'dash.nav.overview':   'Übersicht',
+  'dash.nav.settings':   'Einstellungen',
+  'dash.nav.backToSite': '← Zurück zur Seite',
+
+  'overview.heading':       'Übersicht',
+  'overview.intro':         'Du bist durch das Gate — diese Seite wird nur für angemeldete Besucher gerendert.',
+  'overview.stat.projects': 'Projekte',
+  'overview.stat.members':  'Mitglieder',
+  'overview.stat.issues':   'Offene Vorgänge',
+  'overview.stat.uptime':   'Verfügbarkeit',
+
+  'settings.heading': 'Einstellungen',
+  'settings.intro':   'Kontospezifische Einstellungen würden hier stehen.',
+  'settings.signOut': 'Abmelden',
+
+  'error.heading':    'Etwas ist schiefgelaufen',
+  'error.retry':      'Erneut versuchen',
+  'notFound.heading': 'Nicht gefunden',
+  'notFound.body':    'Diese Dashboard-Seite existiert nicht.',
+  'notFound.back':    '← Zurück zur Übersicht',
+})

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

@@ -0,0 +1,60 @@
+// 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, `{n, plural, …}`, 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 + description — locale-aware via each page's `meta({ locale })`.
+  'meta.landing.title':       'Welcome',
+  'meta.landing.description': 'A Voltro dashboard starter — public marketing pages + an auth-gated app shell.',
+  'meta.login.title':         'Sign in',
+  'meta.overview.title':      'Overview',
+  'meta.settings.title':      'Settings',
+
+  // ---- Marketing header ((marketing)/layout.tsx) ----
+  'nav.dashboard': 'Dashboard',
+  'nav.signIn':    'Sign in',
+  'lang.label':    'Language',
+
+  // ---- Public landing ((marketing)/index.tsx) ----
+  'landing.heading': 'Your app, with the boring parts done.',
+  'landing.body':    'This template ships a public marketing area (a silent <code>(marketing)</code> route group) and a <code>/dashboard</code> area gated by a layout loader — try opening <dash>/dashboard</dash> while signed out and you’ll be redirected to <login>/login</login>.',
+  'landing.cta':     'Sign in to continue →',
+
+  // ---- Public sign-in ((marketing)/login.tsx) ----
+  'login.heading': 'Sign in',
+  'login.body':    'No real auth here — this button just sets a demo session cookie so you can see the dashboard gate let you through.',
+  'login.cta':     'Continue as Demo User →',
+
+  // ---- Dashboard shell (dashboard/layout.tsx) ----
+  'dash.planSuffix':     '· {plan} plan',
+  'dash.nav.overview':   'Overview',
+  'dash.nav.settings':   'Settings',
+  'dash.nav.backToSite': '← Back to site',
+
+  // ---- Dashboard overview (dashboard/index.tsx) ----
+  'overview.heading':       'Overview',
+  'overview.intro':         'You’re past the gate — this page only renders for a signed-in visitor.',
+  'overview.stat.projects': 'Projects',
+  'overview.stat.members':  'Members',
+  'overview.stat.issues':   'Open issues',
+  'overview.stat.uptime':   'Uptime',
+
+  // ---- Settings (dashboard/settings.tsx) ----
+  'settings.heading': 'Settings',
+  'settings.intro':   'Per-account settings would live here.',
+  'settings.signOut': 'Sign out',
+
+  // ---- Scoped fallbacks (dashboard/error.tsx, not-found.tsx) ----
+  'error.heading':    'Something went wrong',
+  'error.retry':      'Try again',
+  'notFound.heading': 'Not found',
+  'notFound.body':    'That dashboard page doesn’t exist.',
+  'notFound.back':    '← Back to overview',
+} as const)

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

@@ -0,0 +1,15 @@
+// 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: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

package/templates/apps/frontend-dashboard/src/pages/(marketing)/index.test.tsx

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+//
+// `/` public landing — a static page with fixed content. Assert its render-mode
+// + meta config and the hero copy / links.
+
+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: Landing, meta, renderMode } = await import('./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> (the framework auto-wires
+// this in the running app). Wrap with the real English catalog.
+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('landing — config', () => {
+  test('pre-renders as a static page with title + description meta', () => {
+    expect(renderMode).toBe('static')
+    expect(meta({ locale: 'en' }).title).toBe('Welcome')
+    expect(meta({ locale: 'en' }).description).toContain('marketing')
+  })
+})
+
+describe('landing — render', () => {
+  test('renders the hero heading and a sign-in call to action', () => {
+    render(createElement(Landing))
+    expect(container.querySelector('h1')!.textContent).toContain('boring parts')
+    const cta = Array.from(container.querySelectorAll('a')).find(
+      (a) => a.getAttribute('href') === '/login' && (a.textContent ?? '').includes('Sign in'),
+    )
+    expect(cta).toBeTruthy()
+  })
+})

package/templates/apps/frontend-dashboard/src/pages/(marketing)/index.tsx

@@ -0,0 +1,34 @@
+// Public landing — URL `/` (the `(marketing)` group is silent). Pure static
+// content, so it pre-renders to flat HTML and ships zero JS by default.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.landing.title'],
+  description: getCatalog(locale)['meta.landing.description'],
+})
+
+export default function Landing(): ReactNode {
+  return (
+    <section className="hero">
+      <h1><T id="landing.heading" /></h1>
+      <p className="muted">
+        <T
+          id="landing.body"
+          values={{
+            code: (c: ReactNode) => <code>{c}</code>,
+            dash: (c: ReactNode) => <a href="/dashboard">{c}</a>,
+            login: (c: ReactNode) => <a href="/login">{c}</a>,
+          }}
+        />
+      </p>
+      <p style={{ marginTop: '1.5rem' }}>
+        <a className="btn" href="/login"><T id="landing.cta" /></a>
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,32 @@
+// Layout for the SILENT route group `(marketing)/`. The parens mean the
+// directory name never appears in a URL — the pages inside are `/` and
+// `/login`, NOT `/(marketing)/...`. A route group exists purely to organise
+// files + scope a shared layout to a set of pages without inventing a URL
+// segment for it. Here it gives the public pages a marketing header/footer
+// distinct from the dashboard's sidebar shell.
+import type { ReactNode } from 'react'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../../config'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export default function MarketingLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  return (
+    <div className="marketing">
+      <header>
+        <a className="brand" href="/">{APP_NAME}</a>
+        <span className="spacer" />
+        <a href="/dashboard"><T id="nav.dashboard" /></a>
+        <a href="/login"><T id="nav.signIn" /></a>
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+      </header>
+      {children}
+    </div>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/(marketing)/login.test.tsx

@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+//
+// `/login` demo sign-in. Clicking "Continue" sets the demo session cookie and
+// navigates to `?from=` (defaulting to /dashboard). We mock useNavigate from
+// @voltro/web and drive the click, asserting cookie + navigation target.
+
+import { afterEach, beforeEach, describe, expect, test, vi } 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 navigate = vi.fn<(to: string) => void>()
+vi.mock('@voltro/web', () => ({ useNavigate: () => navigate }))
+
+const { default: Login, meta, renderMode } = await import('./login')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>, so wrap the render in an <I18nProvider> (auto-wired in 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 }),
+    )
+  })
+}
+
+const clickContinue = (): void => {
+  const btn = container.querySelector('button')!
+  act(() => { btn.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+}
+
+beforeEach(() => {
+  navigate.mockReset()
+  // Clear any stale cookie between tests.
+  document.cookie = 'demo_session=; path=/; max-age=0'
+})
+
+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 — sign in', () => {
+  test('sets the session cookie and navigates to /dashboard by default', () => {
+    render(createElement(Login))
+    clickContinue()
+    expect(document.cookie).toContain('demo_session=ok')
+    expect(navigate).toHaveBeenCalledWith('/dashboard')
+  })
+
+  test('honours the ?from= redirect target', () => {
+    window.history.replaceState({}, '', '/login?from=/dashboard/settings')
+    render(createElement(Login))
+    clickContinue()
+    expect(navigate).toHaveBeenCalledWith('/dashboard/settings')
+  })
+})

package/templates/apps/frontend-dashboard/src/pages/(marketing)/login.tsx

@@ -0,0 +1,40 @@
+// Public sign-in page — URL `/login`. The shell pre-renders (`static`) and
+// hydrates for the button. This is a DEMO login: it just writes the cookie
+// the dashboard gate looks for. A real app POSTs credentials to an api that
+// returns a signed, HttpOnly session cookie — see AGENTS.md › Auth.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useNavigate } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+import { SESSION_COOKIE } from '../../lib/auth'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.login.title'],
+})
+
+export default function Login(): ReactNode {
+  const navigate = useNavigate()
+
+  const onSignIn = (): void => {
+    // Set the demo session cookie, then go where the gate sent us (the
+    // RedirectError carries `?from=`), defaulting to the dashboard.
+    document.cookie = `${SESSION_COOKIE}=ok; path=/; max-age=86400; samesite=lax`
+    const from = new URLSearchParams(window.location.search).get('from') ?? '/dashboard'
+    navigate(from)
+  }
+
+  return (
+    <section className="hero">
+      <h1><T id="login.heading" /></h1>
+      <p className="muted"><T id="login.body" /></p>
+      <p style={{ marginTop: '1.5rem' }}>
+        <button type="button" className="btn" onClick={onSignIn}>
+          <T id="login.cta" />
+        </button>
+      </p>
+    </section>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/dashboard/error.tsx

@@ -0,0 +1,21 @@
+// Error boundary scoped to the /dashboard subtree. A render error (or a
+// loader rejection that ISN'T a RedirectError / NotFoundError) in any
+// dashboard page bubbles to the nearest `error.tsx` — this one — instead of
+// the router's default. `reset` re-runs the failed segment.
+import type { ReactNode } from 'react'
+import type { ErrorBoundaryProps } from '@voltro/web'
+import { T } from '@voltro/i18n'
+
+export default function DashboardError({ 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-dashboard/src/pages/dashboard/fallbacks.test.tsx

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+//
+// Render smokes for the /dashboard subtree's scoped fallbacks: error.tsx
+// (message + reset button), loading.tsx (skeleton), not-found.tsx (message +
+// back link). These are pure presentational components with no framework hooks.
+
+import { afterEach, describe, expect, test, vi } 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: DashboardError } = await import('./error')
+const { default: DashboardLoading } = await import('./loading')
+const { default: DashboardNotFound } = await import('./not-found')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// error.tsx / not-found.tsx use <T>, so wrap renders in the framework's
+// <I18nProvider> (auto-wired 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 }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('dashboard error boundary', () => {
+  test('renders the error text and calls reset when Try again is clicked', () => {
+    const reset = vi.fn()
+    render(createElement(DashboardError, { error: new Error('kaboom'), reset }))
+    expect(container.textContent).toContain('kaboom')
+    const btn = container.querySelector('button')!
+    act(() => { btn.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    expect(reset).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('dashboard loading', () => {
+  test('renders skeleton placeholders', () => {
+    render(createElement(DashboardLoading))
+    expect(container.querySelectorAll('.skeleton').length).toBeGreaterThan(0)
+  })
+})
+
+describe('dashboard not-found', () => {
+  test('renders the not-found message and a link back to the overview', () => {
+    render(createElement(DashboardNotFound))
+    expect(container.textContent).toContain('Not found')
+    const back = Array.from(container.querySelectorAll('a')).find(
+      (a) => a.getAttribute('href') === '/dashboard',
+    )
+    expect(back).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+//
+// `/dashboard` overview — the SSR overview page. It has no loader/hooks; it
+// renders a fixed set of stat cards + declares its render mode + meta. We assert
+// those config exports and the rendered card structure.
+
+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: Overview, meta, renderMode } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>, so wrap renders in the framework's <I18nProvider>.
+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('dashboard overview — config', () => {
+  test('is an SSR page (so the parent gate runs per request) with an Overview title', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Overview')
+  })
+})
+
+describe('dashboard overview — render', () => {
+  test('renders one card per stat with its label and value', () => {
+    render(createElement(Overview))
+    const cards = Array.from(container.querySelectorAll('.card'))
+    expect(cards).toHaveLength(4)
+    expect(container.textContent).toContain('Projects')
+    expect(container.textContent).toContain('12')
+    expect(container.textContent).toContain('Uptime')
+    expect(container.textContent).toContain('99.9%')
+  })
+})