@voltro/cli 0.1.0

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

@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+//
+// `/admin` overview — renders one card per discovered entity (from the api
+// capability map), an error banner if the map can't be reached, and a skeleton
+// while loading. We mock @voltro/client so the three states are driveable.
+
+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'
+
+interface ManifestState { manifest: unknown; loading: boolean; error?: unknown }
+const capabilityManifest = vi.fn<() => ManifestState>()
+const entityAdmins = vi.fn<() => Array<Record<string, unknown>>>()
+
+vi.mock('@voltro/client', () => ({
+  useCapabilityManifest: () => capabilityManifest(),
+  deriveEntityAdmins: () => entityAdmins(),
+}))
+
+const { default: AdminOverview, meta, renderMode } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// AdminOverview 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 }),
+    )
+  })
+}
+
+beforeEach(() => {
+  capabilityManifest.mockReset()
+  entityAdmins.mockReset()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('admin overview — config', () => {
+  test('is an SSR page titled Overview', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Overview')
+  })
+})
+
+describe('admin overview — render', () => {
+  test('renders a linked card per entity with its column count and ops', () => {
+    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+    entityAdmins.mockReturnValue([
+      { table: 'todos', columns: ['id', 'title'], reactive: true, listTag: 'todos.list', createTag: 'todos.create' },
+      { table: 'notes', columns: ['id'], reactive: false, listTag: 'notes.list' },
+    ])
+
+    render(createElement(AdminOverview))
+    const cards = Array.from(container.querySelectorAll('a.card'))
+    expect(cards.map((c) => c.getAttribute('href'))).toEqual(['/admin/todos', '/admin/notes'])
+    expect(container.textContent).toContain('2 columns · reactive')
+    expect(container.textContent).toContain('1 column')
+    expect(container.textContent).toContain('list · create')
+  })
+
+  test('shows the error banner when the capability map is unreachable', () => {
+    capabilityManifest.mockReturnValue({ manifest: undefined, loading: false, error: 'boom' })
+    entityAdmins.mockReturnValue([])
+    render(createElement(AdminOverview))
+    expect(container.querySelector('.banner')!.textContent).toContain('Couldn’t reach')
+  })
+
+  test('shows skeleton cards while the manifest is loading', () => {
+    capabilityManifest.mockReturnValue({ manifest: undefined, loading: true })
+    entityAdmins.mockReturnValue([])
+    render(createElement(AdminOverview))
+    expect(container.querySelectorAll('.skeleton').length).toBeGreaterThan(0)
+  })
+})

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

@@ -0,0 +1,65 @@
+// Admin overview — URL `/admin`. `renderMode: 'ssr'` so the parent layout's
+// auth gate runs per request. Renders one card per discovered entity, each
+// linking to its CRUD page. The whole list comes from the api's capability map
+// — there's no hard-coded entity list.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useCapabilityManifest, deriveEntityAdmins } from '@voltro/client'
+import { T } 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.overview.title'],
+})
+
+export default function AdminOverview(): ReactNode {
+  const { manifest, loading, error } = useCapabilityManifest('app')
+  const entities = manifest ? deriveEntityAdmins(manifest) : []
+
+  return (
+    <section>
+      <h1><T id="overview.heading" /></h1>
+      <p className="muted">
+        <T id="overview.intro" values={{ code: (c: ReactNode) => <code>{c}</code> }} />
+      </p>
+
+      {error ? (
+        <p className="banner" style={{ marginTop: '1rem' }}>
+          <T id="overview.error" />
+        </p>
+      ) : null}
+
+      {loading && entities.length === 0 ? (
+        <div className="cards" style={{ marginTop: '1.25rem' }} aria-hidden="true">
+          <div className="skeleton" /><div className="skeleton" /><div className="skeleton" />
+        </div>
+      ) : (
+        <div className="cards" style={{ marginTop: '1.25rem' }}>
+          {entities.map((e) => {
+            const ops = [
+              e.listTag && 'list',
+              e.createTag && 'create',
+              e.updateTag && 'edit',
+              e.deleteTag && 'delete',
+            ].filter(Boolean)
+            return (
+              <a className="card" key={e.table} href={`/admin/${e.table}`}>
+                <div className="value">{e.table}</div>
+                <div className="label">
+                  <T id="overview.columns" values={{ count: e.columns.length }} />
+                  {e.reactive ? <T id="overview.reactiveSuffix" /> : null}
+                </div>
+                <div className="meta">{ops.length > 0 ? ops.join(' · ') : <T id="overview.readonly" />}</div>
+              </a>
+            )
+          })}
+          {entities.length === 0 && !loading ? (
+            <p className="muted"><T id="overview.empty" /></p>
+          ) : null}
+        </div>
+      )}
+    </section>
+  )
+}

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

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+//
+// The admin shell + AUTH GATE. The loader redirects an unauthenticated request
+// and otherwise returns the shared user. The rendered shell derives its nav
+// from the api capability map (useCapabilityManifest + deriveEntityAdmins) and
+// wraps an undo/redo bar (useUndoLog). We mock @voltro/client so those hooks are
+// deterministic, mock the framework hooks, and import the REAL RedirectError.
+
+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 { RedirectError } from '@voltro/web'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../locales/en'
+
+const loaderData = vi.fn<() => unknown>()
+const location = vi.fn<() => string>()
+
+vi.mock('@voltro/web', async () => {
+  const actual = await vi.importActual<typeof import('@voltro/web')>('@voltro/web')
+  return { ...actual, useLoaderData: () => loaderData(), useLocation: () => location() }
+})
+
+interface ManifestState { manifest: unknown; loading: boolean }
+const capabilityManifest = vi.fn<() => ManifestState>()
+const entityAdmins = vi.fn<() => Array<{ table: string }>>()
+const undoLog = vi.fn(() => ({
+  canUndo: false,
+  canRedo: false,
+  undoLast: vi.fn(),
+  redoLast: vi.fn(),
+}))
+
+vi.mock('@voltro/client', () => ({
+  useCapabilityManifest: () => capabilityManifest(),
+  deriveEntityAdmins: () => entityAdmins(),
+  useUndoLog: () => undoLog(),
+  PermissionProvider: ({ children }: { children?: ReactNode }) => children,
+}))
+
+const { default: AdminLayout, loader } = await import('./layout')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// AdminLayout uses <T>/useLocale + <LocaleSwitcher>, 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 }),
+    )
+  })
+}
+
+beforeEach(() => {
+  loaderData.mockReset()
+  location.mockReset()
+  capabilityManifest.mockReset()
+  entityAdmins.mockReset()
+  undoLog.mockClear()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('admin layout — loader (auth gate)', () => {
+  test('redirects to /login (remembering the destination) when unauthenticated', async () => {
+    const err = await Promise.resolve(loader({ headers: {} } as never)).catch((e: unknown) => e)
+    expect(err).toBeInstanceOf(RedirectError)
+    expect((err as RedirectError).location).toBe('/login?from=/admin')
+  })
+
+  test('returns the shared user for a signed-in request', async () => {
+    const data = await loader({ headers: { cookie: 'demo_session=ok' } } as never)
+    expect(data.user.name).toBe('Demo Admin')
+  })
+})
+
+describe('admin layout — render', () => {
+  test('renders a nav item per discovered entity plus the Overview link', () => {
+    loaderData.mockReturnValue({ user: { name: 'Root Admin' } })
+    location.mockReturnValue('/admin')
+    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+    entityAdmins.mockReturnValue([{ table: 'todos' }, { table: 'projects' }])
+
+    render(createElement(AdminLayout, { children: createElement('p', null, 'admin body') }))
+
+    expect(container.textContent).toContain('Root Admin')
+    const hrefs = Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+    expect(hrefs).toContain('/admin')
+    expect(hrefs).toContain('/admin/todos')
+    expect(hrefs).toContain('/admin/projects')
+    expect(container.querySelector('main')!.textContent).toContain('admin body')
+  })
+
+  test('shows the discovering hint before the manifest arrives', () => {
+    loaderData.mockReturnValue({ user: { name: 'Root Admin' } })
+    location.mockReturnValue('/admin')
+    capabilityManifest.mockReturnValue({ manifest: undefined, loading: true })
+    entityAdmins.mockReturnValue([])
+
+    render(createElement(AdminLayout, { children: null }))
+    expect(container.textContent).toContain('discovering…')
+  })
+})

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

@@ -0,0 +1,97 @@
+// The admin shell — and the AUTH GATE. This nested layout wraps every page
+// under `/admin`, and its `loader` runs server-side BEFORE the page renders, so
+// it's the right seam to validate the session. Throwing RedirectError
+// short-circuits the subtree (303 + Location on SSR; replace-nav on the client).
+// Pages under here are `renderMode: 'ssr'` so the gate runs per request.
+//
+// The sidebar is DRIVEN BY THE API'S CAPABILITY MAP: useCapabilityManifest +
+// deriveEntityAdmins discover every entity at runtime, so point the admin at any
+// api and the nav adapts — no per-entity code. The undo bar wraps the
+// __voltro.undo.* built-ins (requires undo capture on; the dev default).
+import type { ReactNode } from 'react'
+import { RedirectError, useLoaderData, useLocation, type LoaderFn } from '@voltro/web'
+import {
+  useCapabilityManifest,
+  deriveEntityAdmins,
+  useUndoLog,
+  PermissionProvider,
+} from '@voltro/client'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../../config'
+import { isSignedIn } from '../../lib/auth'
+import { DEMO_SCOPES } from '../../lib/admin'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export const renderMode = 'ssr' as const
+
+interface AdminData {
+  readonly user: { readonly name: string }
+}
+
+export const loader: LoaderFn<AdminData> = async ({ headers }) => {
+  if (!isSignedIn(headers)) {
+    throw new RedirectError('/login?from=/admin')
+  }
+  return { user: { name: 'Demo Admin' } }
+}
+
+// The undo bar — split out so a deployment running with VOLTRO_UNDO=off (no
+// __voltro.undo.* built-ins) can delete just these lines.
+const UndoBar = (): ReactNode => {
+  const undo = useUndoLog('app')
+  return (
+    <>
+      <button type="button" className="btn ghost" disabled={!undo.canUndo} onClick={() => void undo.undoLast()}>
+        <T id="admin.undo" />
+      </button>
+      <button type="button" className="btn ghost" disabled={!undo.canRedo} onClick={() => void undo.redoLast()}>
+        <T id="admin.redo" />
+      </button>
+    </>
+  )
+}
+
+export default function AdminLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  const { user } = useLoaderData<AdminData>()
+  const pathname = useLocation()
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  const { manifest, loading } = useCapabilityManifest('app')
+  const entities = manifest ? deriveEntityAdmins(manifest) : []
+
+  const navItem = (href: string, label: ReactNode): ReactNode => (
+    <a key={href} href={href} aria-current={pathname === href ? 'page' : undefined}>{label}</a>
+  )
+
+  return (
+    // PermissionProvider feeds the current subject's scopes to useCan across the
+    // admin. DEMO scopes here — swap for your session's scopes (see lib/admin.ts).
+    <PermissionProvider scopes={DEMO_SCOPES}>
+      <div className="admin">
+        <aside>
+          <div className="brand">{APP_NAME}</div>
+          <nav>
+            {navItem('/admin', <T id="admin.nav.overview" />)}
+            {loading && entities.length === 0 ? <span className="muted" style={{ padding: '0.35rem 0.6rem', fontSize: '0.85rem' }}><T id="admin.nav.discovering" /></span> : null}
+            {entities.map((e) => navItem(`/admin/${e.table}`, e.table))}
+            <a href="/"><T id="admin.nav.backToSite" /></a>
+          </nav>
+        </aside>
+        <main>
+          <div className="topbar">
+            <strong>{user.name}</strong>
+            <span className="spacer" />
+            <UndoBar />
+            <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+          </div>
+          {children}
+        </main>
+      </div>
+    </PermissionProvider>
+  )
+}

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

@@ -0,0 +1,15 @@
+// OPT-IN loading skeleton for /admin pages. Suits a data-backed admin where the
+// loader (auth gate) + the first capability-map fetch take a beat.
+import type { ReactNode } from 'react'
+
+export default function AdminLoading(): ReactNode {
+  return (
+    <div className="admin">
+      <main>
+        <div className="cards" aria-hidden="true">
+          <div className="skeleton" /><div className="skeleton" /><div className="skeleton" />
+        </div>
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-admin/src/pages/admin/not-found.tsx

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

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

@@ -0,0 +1,12 @@
+// Root layout — wraps EVERY page (marketing + admin). Intentionally thin: it
+// loads the stylesheet and lets each AREA layout ((marketing)/layout.tsx,
+// admin/layout.tsx) supply its own chrome. Layouts nest, so an admin page is
+// wrapped root → admin.
+//
+// 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-admin/src/pages/layouts.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+//
+// Render smokes for the root layout (passes children through) and the
+// (marketing) group layout (brand header + nav links wrapping the children).
+
+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: RootLayout } = await import('./layout')
+const { default: MarketingLayout } = await import('./(marketing)/layout')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// MarketingLayout uses <T>/useLocale + <LocaleSwitcher>, 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('root layout', () => {
+  test('renders its children unchanged', () => {
+    render(createElement(RootLayout, { children: createElement('p', null, 'hello') }))
+    expect(container.textContent).toContain('hello')
+  })
+})
+
+describe('marketing layout', () => {
+  test('renders the header nav (Admin + Sign in) around the children', () => {
+    render(createElement(MarketingLayout, { children: createElement('p', null, 'body') }))
+    const hrefs = Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+    expect(hrefs).toContain('/admin')
+    expect(hrefs).toContain('/login')
+    expect(container.textContent).toContain('body')
+  })
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-admin",
+  "kind": "web",
+  "summary": "An auto-admin back-office that DISCOVERS your api's entities at runtime (capability map) and renders a live, reactive <DataTable> + <AutoForm> per entity — permission-gated with useCan, with a per-row provenance drawer and universal undo/redo. Editable template code, not a sealed generated cage. Pairs with any api: scaffold both with `create-project --api=api-backend --web=frontend-admin`.",
+  "tags": ["web", "frontend", "admin", "back-office", "schema-driven", "datatable", "autoform", "rbac", "undo", "provenance", "reactive"]
+}

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

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

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

@@ -0,0 +1,98 @@
+# {{projectName}} / {{appName}}
+
+Voltro frontend scaffold (template: **frontend-app**).
+
+The **reactive end-to-end loop** — the framework's headline feature, in one
+page. A live notes list (`useSubscription`) plus a create form
+(`useMutation`) with **zero-boilerplate auto-optimistic** updates. This is the
+only template that wires a web frontend to an api; every other `frontend-*`
+template is backend-less.
+
+## Scaffold the pair
+
+`frontend-app` consumes a sibling api — it is meant to be scaffolded **together
+with [`api-backend`](../api-backend)** (which exposes the `notes.list` query +
+`notes.create` mutation this page subscribes to / calls):
+
+```bash
+voltro create-project demo --api=api-backend --web=frontend-app
+cd demo
+pnpm install
+pnpm dev            # boots BOTH apps (api on :4000, web on its portRange port)
+```
+
+Open the web app, add a note, and watch it appear in the list **instantly** —
+no refetch, no polling. Open a second browser tab: a note added in one tab
+shows up live in the other.
+
+## How the loop works
+
+```
+ Browser                         api (api-backend)
+ ───────                         ─────────────────
+ useSubscription('app',          notes.list  (defineQuery, source: 'notes')
+   'notes.list')  ───WS────►       └─ streams a fresh snapshot/delta on every
+        ▲                              write to the tenant's `notes` rows
+        │ delta (WebSocket)
+        │
+ useMutation('app',              notes.create  (defineMutation,
+   'notes.create')  ──rpc──►       target: { table:'notes', op:'insert' })
+   .mutate({...})                   └─ one atomic DB write → commit → delta
+```
+
+1. **`useSubscription('app', 'notes.list')`** opens ONE live WebSocket
+   subscription. `data` is the current rows; it re-renders whenever the
+   `notes` table changes — from THIS tab, another tab, a workflow, or an
+   out-of-band DB write.
+2. **`useMutation('app', 'notes.create').mutate({...})`** invokes the
+   mutation. Because the descriptor declares `target: { table:'notes',
+   op:'insert' }`, the framework **auto-prepends an optimistic row** to the
+   subscription the instant you submit — then replaces it with the real row
+   (or reverts it) when the rpc resolves. No `.withOptimistic`, no
+   `useOptimistic`, no `startTransition`.
+
+Optimistic rows carry `optimistic: true`; the page renders them faintly until
+the server delta supersedes them (see `src/pages/index.tsx`).
+
+## The `apis` wiring
+
+```ts
+// app.config.ts
+apis: {
+  app: { package: '@{{projectName}}/api' },   // the sibling api in this project
+}
+```
+
+The map key (`'app'`) is the **lookup name** every hook takes as its first
+argument — `useSubscription('app', …)`, `useMutation('app', …)`. The
+`package` resolves the sibling api workspace package; its port is
+auto-discovered from its own `app.config.ts`, and codegen pulls its typed rpc
+surface. Consume more apis by adding more entries (each gets its own
+WebSocket + reconnect cycle).
+
+## Files
+
+```
+app.config.ts            type:web + the `apis: { app }` wiring
+package.json             depends on @{{projectName}}/api (the sibling) + @voltro/client
+src/pages/
+  layout.tsx             root shell (header + <main>)
+  index.tsx              the reactive notes page — useSubscription + useMutation
+```
+
+## Pairing with a different api
+
+This page is hard-wired to api-backend's `notes` domain. To point it at your
+own api, change `app.config.ts`'s `apis.app.package`, then swap the rpc tags +
+the `Note` type in `src/pages/index.tsx` to match your query/mutation
+descriptors. The hook shapes (`useSubscription` / `useMutation`) are identical
+for any api.
+
+## Multi-tenancy note
+
+The dev `AuthMiddleware` resolves the tenant from the `x-tenant` header,
+defaulting to `'acme'` (the `TENANT` constant in `index.tsx`). The `notes`
+table carries the `tenant()` mixin, so reads are auto-scoped and
+`notes.create` guards that the submitted `tenantId` matches the caller's —
+a typed `TenantMismatch` otherwise. Wire real auth before production (see the
+authentication docs).

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

@@ -0,0 +1,43 @@
+// Web app for the {{projectName}} project. Read by `voltro dev` / `voltro start`.
+//
+// This is the FULLSTACK template — a web frontend wired to an api so you can
+// see the framework's headline feature: the reactive end-to-end loop. The web
+// client subscribes to a server-side query; when a mutation writes the table,
+// the server pushes a delta over WebSocket and the React tree re-renders. No
+// `refetch`, no polling.
+//
+// `port` is allocated by `voltro create-project` / `voltro add-app` from the
+// project's portRange (in project.json), hard-pinned per app.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed PUBLIC environment — public vars are validated + baked into the browser
+// bundle at build time and read via `publicEnv` from '@voltro/env/public'.
+// NEVER put a secret here (it ships to every visitor) — declare secrets on the
+// api instead. Run `voltro env` for the manifest.
+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}},
+  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 with no manual setup. The <LocaleSwitcher>
+  // in the layout writes the `voltro:lang` cookie + reloads. Grow the app to
+  // more languages by adding a code here + a `src/locales/<code>.ts`.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  // The api this frontend consumes. The NAME ('app') is the lookup key the
+  // hooks use — `useSubscription('app', 'notes.list')`, `useMutation('app',
+  // 'notes.create')`. The `package` resolves the sibling api in this project
+  // (scaffold it with `--api=api-backend`); its port is auto-discovered from
+  // its own app.config.ts, and codegen pulls its typed rpc surface so the
+  // hooks are end-to-end typed. Add more entries to consume more apis.
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

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

@@ -0,0 +1,30 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@{{projectName}}/api": "0.1.0",
+    "@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"
+  }
+}