@voltro/cli 0.1.0

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

@@ -0,0 +1,79 @@
+// 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':       'Admin',
+  'meta.landing.description': 'An auto-admin back-office that discovers your api’s entities and renders a live, permission-gated, undoable UI per entity.',
+  'meta.login.title':         'Sign in',
+  'meta.overview.title':      'Overview',
+  'meta.entity.title':        'Entity',
+
+  // ---- Marketing header ((marketing)/layout.tsx) ----
+  'nav.admin':  'Admin',
+  'nav.signIn': 'Sign in',
+  'lang.label': 'Language',
+
+  // ---- Public landing ((marketing)/index.tsx) ----
+  'landing.heading': 'The back-office, done for you.',
+  'landing.body':    'This admin reads your api’s <strong>capability map</strong> at runtime and renders a live, reactive <code>DataTable</code> + <code>AutoForm</code> for every entity it exposes — permission-gated with <code>useCan</code>, with a per-row provenance drawer and universal undo/redo. Point it at any Voltro api and it adapts; the page code under <code>src/pages/admin/</code> is yours to edit.',
+  'landing.cta':     'Sign in to the admin →',
+
+  // ---- Public sign-in ((marketing)/login.tsx) ----
+  'login.heading': 'Sign in',
+  'login.body':    'No real auth here — this button sets a demo session cookie so you can see the admin gate let you through.',
+  'login.cta':     'Continue as Demo Admin →',
+
+  // ---- Admin shell (admin/layout.tsx) ----
+  'admin.undo':           '↶ Undo',
+  'admin.redo':           '↷ Redo',
+  'admin.nav.overview':   'Overview',
+  'admin.nav.discovering': 'discovering…',
+  'admin.nav.backToSite': '← Back to site',
+
+  // ---- Admin overview (admin/index.tsx) ----
+  'overview.heading':        'Entities',
+  'overview.intro':          'Discovered from <code>app</code>’s capability map. Each card is a live, permission-gated CRUD view — no per-entity code.',
+  'overview.error':          'Couldn’t reach the api’s capability map. Is the api running with inspect enabled?',
+  'overview.columns':        '{count, plural, one {# column} other {# columns}}',
+  'overview.reactiveSuffix': ' · reactive',
+  'overview.readonly':       'read-only',
+  'overview.empty':          'No user entities exposed by this api.',
+
+  // ---- Per-entity CRUD (admin/[entity].tsx) ----
+  'entity.create':  'Create',
+  'entity.addLabel': 'Add {table}',
+  'entity.rows':    'Rows',
+  'entity.noList':  'This entity exposes no list query.',
+  'entity.empty':   'No {table} yet.',
+  'entity.why':     'Why?',
+  'entity.delete':  'Delete',
+  'entity.unknown': 'No entity <code>{entity}</code> in this api’s capability map.',
+
+  // ---- Provenance drawer (admin/[entity].tsx) ----
+  'prov.title':       'Provenance · <code>{table}</code> #{id}',
+  'prov.close':       'close',
+  'prov.loading':     'loading…',
+  'prov.none':        'No provenance (is audit() on this table + inspect enabled?).',
+  'prov.lastWrite':   'last write',
+  'prov.byActor':     'by actor',
+  'prov.attribution': 'attribution',
+  'prov.via':         ' (via {via})',
+  'prov.derived':     'derived',
+  'prov.yes':         'yes',
+
+  // ---- Scoped fallbacks (admin/error.tsx, not-found.tsx) ----
+  'error.heading':   'Something went wrong',
+  'error.retry':     'Try again',
+  'notFound.heading': 'Not found',
+  'notFound.body':   'That admin page doesn’t exist.',
+  'notFound.back':   '← Back to overview',
+} as const)

package/templates/apps/frontend-admin/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-admin/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 / sign-in link.
+
+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('Admin')
+    expect(meta({ locale: 'en' }).description).toContain('back-office')
+  })
+})
+
+describe('landing — render', () => {
+  test('renders the hero heading and a sign-in call to action', () => {
+    render(createElement(Landing))
+    expect(container.querySelector('h1')!.textContent).toContain('back-office')
+    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-admin/src/pages/(marketing)/index.tsx

@@ -0,0 +1,32 @@
+// Public landing — URL `/`. Pure static content; pre-renders to flat HTML.
+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={{
+            strong: (c: ReactNode) => <strong>{c}</strong>,
+            code: (c: ReactNode) => <code>{c}</code>,
+          }}
+        />
+      </p>
+      <p style={{ marginTop: '1.5rem' }}>
+        <a className="btn" href="/login"><T id="landing.cta" /></a>
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,29 @@
+// Layout for the SILENT route group `(marketing)/`. The parens mean the
+// directory name never appears in a URL — the pages inside are `/` and
+// `/login`. Gives the public pages a header distinct from the admin sidebar.
+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="/admin"><T id="nav.admin" /></a>
+        <a href="/login"><T id="nav.signIn" /></a>
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+      </header>
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+//
+// `/login` demo sign-in. Clicking "Continue" sets the demo session cookie and
+// navigates to `?from=` (defaulting to /admin). We mock useNavigate from
+// @voltro/web and drive the click.
+
+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()
+  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 /admin by default', () => {
+    render(createElement(Login))
+    clickContinue()
+    expect(document.cookie).toContain('demo_session=ok')
+    expect(navigate).toHaveBeenCalledWith('/admin')
+  })
+
+  test('honours the ?from= redirect target', () => {
+    window.history.replaceState({}, '', '/login?from=/admin/todos')
+    render(createElement(Login))
+    clickContinue()
+    expect(navigate).toHaveBeenCalledWith('/admin/todos')
+  })
+})

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

@@ -0,0 +1,35 @@
+// Public sign-in — URL `/login`. DEMO login: it just writes the cookie the
+// admin 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 => {
+    document.cookie = `${SESSION_COOKIE}=ok; path=/; max-age=86400; samesite=lax`
+    const from = new URLSearchParams(window.location.search).get('from') ?? '/admin'
+    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-admin/src/pages/admin/[entity].tsx

@@ -0,0 +1,121 @@
+// Per-entity CRUD — URL `/admin/<entity>`. Everything here is DISCOVERED:
+// useCapabilityManifest → deriveEntityAdmins gives this entity's list query +
+// create/update/delete mutation tags + the columns. We bind the shipped
+// schema-driven components to those tags:
+//   - <DataTable api="app" query={listTag}/>  — live, reactive rows
+//   - <AutoForm  api="app" mutation={createTag}/> — fields from the input schema
+// Writes are gated by useCan on the conventional `<table>:create|delete` scopes;
+// each row has a provenance ("why is this here?") drawer (08) + delete; the
+// layout's undo bar reverts the last change (00/09). Edit this file freely — it's
+// your template code, not a sealed runtime feature.
+import { useState, type ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useParams, AutoForm, DataTable } from '@voltro/web'
+import {
+  useCapabilityManifest,
+  deriveEntityAdmins,
+  useCan,
+  useMutation,
+  useProvenance,
+  type EntityAdminSpec,
+} from '@voltro/client'
+import { T, useTFn } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.entity.title'],
+})
+
+type Row = Record<string, unknown>
+
+// "Why is this value here?" — a one-shot provenance lookup (innovation/08).
+// Its own component so useProvenance only runs while the drawer is open.
+const ProvenanceDrawer = ({ table, id, onClose }: { readonly table: string; readonly id: string; readonly onClose: () => void }): ReactNode => {
+  const { data, loading, error } = useProvenance('app', table, id)
+  return (
+    <div className="drawer">
+      <h3>
+        <T id="prov.title" values={{ table, id, code: (c: ReactNode) => <code>{c}</code> }} />
+        {' '}
+        <button type="button" className="btn ghost" style={{ float: 'right' }} onClick={onClose}><T id="prov.close" /></button>
+      </h3>
+      {loading ? <p className="muted"><T id="prov.loading" /></p> : null}
+      {error ? <p className="muted"><T id="prov.none" /></p> : null}
+      {data ? (
+        <dl>
+          <dt><T id="prov.lastWrite" /></dt><dd>{data.lastWrite?.at ?? '—'}</dd>
+          <dt><T id="prov.byActor" /></dt><dd>{data.lastWrite?.actor?.id ?? '—'}{data.lastWrite?.actor?.via ? <T id="prov.via" values={{ via: data.lastWrite.actor.via }} /> : ''}</dd>
+          <dt><T id="prov.attribution" /></dt><dd>{data.attribution}</dd>
+          {data.derived ? <><dt><T id="prov.derived" /></dt><dd><T id="prov.yes" /></dd></> : null}
+        </dl>
+      ) : null}
+    </div>
+  )
+}
+
+// The bound CRUD surface for one entity. A child component so its hooks
+// (useCan/useMutation) get the real spec, never undefined.
+const EntityAdmin = ({ spec }: { readonly spec: EntityAdminSpec }): ReactNode => {
+  const [sel, setSel] = useState<string | null>(null)
+  const t = useTFn()
+  const canCreate = useCan(spec.createScope)
+  const canDelete = useCan(spec.deleteScope)
+  // Always-called; the tag is only used when deleteTag exists (gated below).
+  const del = useMutation<{ id: string }>('app', spec.deleteTag ?? '__voltro.noop')
+
+  const rowActions = (row: Row): ReactNode => {
+    const id = String(row['id'] ?? '')
+    return (
+      <span className="row-actions">
+        <button type="button" className="btn ghost" onClick={() => setSel(id)}><T id="entity.why" /></button>
+        {spec.deleteTag && canDelete && id ? (
+          <button type="button" className="btn danger" onClick={() => void del.mutate({ id })}><T id="entity.delete" /></button>
+        ) : null}
+      </span>
+    )
+  }
+
+  return (
+    <section>
+      <h1>{spec.table}</h1>
+
+      {spec.createTag && canCreate ? (
+        <div className="section">
+          <h2><T id="entity.create" /></h2>
+          <AutoForm api="app" mutation={spec.createTag} submitLabel={t('entity.addLabel', { table: spec.table })} />
+        </div>
+      ) : null}
+
+      <div className="section">
+        <h2><T id="entity.rows" /></h2>
+        {spec.listTag ? (
+          <DataTable api="app" query={spec.listTag} rowActions={rowActions} emptyText={t('entity.empty', { table: spec.table })} />
+        ) : (
+          <p className="muted"><T id="entity.noList" /></p>
+        )}
+        {sel ? <ProvenanceDrawer table={spec.table} id={sel} onClose={() => setSel(null)} /> : null}
+      </div>
+    </section>
+  )
+}
+
+export default function EntityPage(): ReactNode {
+  const { entity } = useParams<{ entity: string }>()
+  const { manifest, loading } = useCapabilityManifest('app')
+  const spec = manifest ? deriveEntityAdmins(manifest).find((e) => e.table === entity) : undefined
+
+  if (loading && !manifest) {
+    return <section><div className="skeleton" style={{ height: '8rem' }} /></section>
+  }
+  if (!spec) {
+    return (
+      <section>
+        <h1>{entity}</h1>
+        <p className="banner"><T id="entity.unknown" values={{ entity, code: (c: ReactNode) => <code>{c}</code> }} /></p>
+      </section>
+    )
+  }
+  return <EntityAdmin spec={spec} />
+}

package/templates/apps/frontend-admin/src/pages/admin/entity.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment jsdom
+//
+// `/admin/<entity>` — per-entity CRUD. It resolves the entity spec from the
+// capability map (useParams + useCapabilityManifest + deriveEntityAdmins) and
+// renders one of three observable states: a loading skeleton, an "unknown
+// entity" banner, or the bound CRUD surface (heading + AutoForm + DataTable).
+// We mock @voltro/web (useParams + the AutoForm/DataTable components) and
+// @voltro/client (the discovery + gating hooks).
+
+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 params = vi.fn<() => { entity?: string }>()
+
+vi.mock('@voltro/web', () => ({
+  useParams: () => params(),
+  AutoForm: ({ mutation }: { mutation: string }) =>
+    createElement('div', { 'data-testid': 'auto-form' }, mutation),
+  DataTable: ({ query }: { query: string }) =>
+    createElement('div', { 'data-testid': 'data-table' }, query),
+}))
+
+interface ManifestState { manifest: unknown; loading: boolean }
+const capabilityManifest = vi.fn<() => ManifestState>()
+const entityAdmins = vi.fn<() => Array<Record<string, unknown>>>()
+const can = vi.fn<() => boolean>()
+
+vi.mock('@voltro/client', () => ({
+  useCapabilityManifest: () => capabilityManifest(),
+  deriveEntityAdmins: () => entityAdmins(),
+  useCan: () => can(),
+  useMutation: () => ({ mutate: vi.fn() }),
+  useProvenance: () => ({ data: undefined, loading: false, error: undefined }),
+}))
+
+const { default: EntityPage, meta, renderMode } = await import('./[entity]')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>/useTFn, 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 }),
+    )
+  })
+}
+
+const cell = (id: string): string | null =>
+  container.querySelector(`[data-testid="${id}"]`)?.textContent ?? null
+
+beforeEach(() => {
+  params.mockReset()
+  capabilityManifest.mockReset()
+  entityAdmins.mockReset()
+  can.mockReset()
+  can.mockReturnValue(true)
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('entity page — config', () => {
+  test('is an SSR page', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Entity')
+  })
+})
+
+describe('entity page — render states', () => {
+  test('shows a skeleton while the manifest is still loading', () => {
+    params.mockReturnValue({ entity: 'todos' })
+    capabilityManifest.mockReturnValue({ manifest: undefined, loading: true })
+    entityAdmins.mockReturnValue([])
+    render(createElement(EntityPage))
+    expect(container.querySelector('.skeleton')).toBeTruthy()
+  })
+
+  test('shows an unknown-entity banner when the entity is not in the map', () => {
+    params.mockReturnValue({ entity: 'ghosts' })
+    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+    entityAdmins.mockReturnValue([{ table: 'todos' }])
+    render(createElement(EntityPage))
+    expect(container.querySelector('.banner')!.textContent).toContain('No entity')
+    expect(container.textContent).toContain('ghosts')
+  })
+
+  test('renders the bound CRUD surface (heading + AutoForm + DataTable) for a known entity', () => {
+    params.mockReturnValue({ entity: 'todos' })
+    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+    entityAdmins.mockReturnValue([
+      {
+        table: 'todos',
+        columns: ['id', 'title'],
+        listTag: 'todos.list',
+        createTag: 'todos.create',
+        createScope: 'todos:create',
+        deleteScope: 'todos:delete',
+        deleteTag: 'todos.delete',
+      },
+    ])
+    render(createElement(EntityPage))
+    expect(container.querySelector('h1')!.textContent).toBe('todos')
+    expect(cell('auto-form')).toBe('todos.create')
+    expect(cell('data-table')).toBe('todos.list')
+  })
+})

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

@@ -0,0 +1,20 @@
+// Error boundary scoped to the /admin subtree. A render error (or a loader
+// rejection that ISN'T a RedirectError / NotFoundError) bubbles to here instead
+// of the router 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 AdminError({ error, reset }: ErrorBoundaryProps): ReactNode {
+  return (
+    <div className="admin">
+      <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-admin/src/pages/admin/fallbacks.test.tsx

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+//
+// Render smokes for the /admin subtree's scoped fallbacks: error.tsx (message +
+// reset), loading.tsx (skeleton), not-found.tsx (message + back link). Pure
+// presentational components, 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: AdminError } = await import('./error')
+const { default: AdminLoading } = await import('./loading')
+const { default: AdminNotFound } = 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('admin error boundary', () => {
+  test('renders the error text and calls reset when Try again is clicked', () => {
+    const reset = vi.fn()
+    render(createElement(AdminError, { 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('admin loading', () => {
+  test('renders skeleton placeholders', () => {
+    render(createElement(AdminLoading))
+    expect(container.querySelectorAll('.skeleton').length).toBeGreaterThan(0)
+  })
+})
+
+describe('admin not-found', () => {
+  test('renders the not-found message and a link back to the overview', () => {
+    render(createElement(AdminNotFound))
+    expect(container.textContent).toContain('Not found')
+    const back = Array.from(container.querySelectorAll('a')).find(
+      (a) => a.getAttribute('href') === '/admin',
+    )
+    expect(back).toBeTruthy()
+  })
+})