@voltro/cli 0.1.0

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

@@ -0,0 +1,36 @@
+// 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 (`{tenant}`, `{revision}`, `{count}`, `{time}`, `{error}`)
+// and rich tags (`<code>`, `<a>`, `<strong>`) identical to `en.ts`.
+
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.notes.title':    'Reaktive Notizen',
+  'meta.schemaUi.title': 'Schema-getriebene UI',
+
+  'nav.notes':    'Notizen',
+  'nav.schemaUi': 'Schema-UI',
+  'nav.tagline':  'Fullstack · reaktiv end-to-end',
+  'lang.label':   'Sprache',
+
+  'notes.heading':        'Reaktive Notizen',
+  'notes.status.tenant':  'Mandant <code>{tenant}</code> · Revision {revision}',
+  'notes.status.delta':   ' · letztes Delta {time}',
+  'notes.status.pending': ' · {count} ausstehend',
+  'notes.status.loading': ' · lädt…',
+  'notes.error':          'Subscription-Fehler — läuft die API? {error}',
+  'notes.field.title':    'Titel',
+  'notes.field.body':     'Text (optional)',
+  'notes.add':            'Notiz hinzufügen',
+  'notes.adding':         'Wird hinzugefügt…',
+  'notes.empty':          'Noch keine Notizen — füge oben eine hinzu und sieh zu, wie sie sofort erscheint.',
+
+  'schemaUi.heading':       'Schema-getriebene UI',
+  'schemaUi.intro':         'Dieselben Notizen wie auf <a>der Startseite</a> — aber Formular + Tabelle sind hier <strong>an Deskriptoren gebunden</strong>, nicht handverdrahtet. Felder kommen aus dem Input-Schema von <code>notes.create</code>; Spalten aus dem Output-Schema von <code>notes.list</code>. Live + optimistisch, ohne Glue-Code.',
+  'schemaUi.createHeading': 'Erstellen (gebunden an <code>notes.create</code>)',
+  'schemaUi.listHeading':   'Liste (gebunden an <code>notes.list</code>)',
+  'schemaUi.submitLabel':   'Notiz hinzufügen',
+  'schemaUi.emptyText':     'Noch keine Notizen — füge oben eine hinzu.',
+})

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

@@ -0,0 +1,43 @@
+// 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 — locale-aware via each page's `meta({ locale })`.
+  'meta.notes.title':    'Reactive notes',
+  'meta.schemaUi.title': 'Schema-driven UI',
+
+  // ---- Layout shell (pages/layout.tsx) ----
+  'nav.notes':    'Notes',
+  'nav.schemaUi': 'Schema UI',
+  'nav.tagline':  'fullstack · reactive end-to-end',
+  'lang.label':   'Language',
+
+  // ---- Notes page (pages/index.tsx) ----
+  'notes.heading':        'Reactive notes',
+  'notes.status.tenant':  'Tenant <code>{tenant}</code> · revision {revision}',
+  'notes.status.delta':   ' · last delta {time}',
+  'notes.status.pending': ' · {count} pending',
+  'notes.status.loading': ' · loading…',
+  'notes.error':          'subscription error — is the api running? {error}',
+  'notes.field.title':    'Title',
+  'notes.field.body':     'Body (optional)',
+  'notes.add':            'Add note',
+  'notes.adding':         'Adding…',
+  'notes.empty':          'No notes yet — add one above and watch it appear instantly.',
+
+  // ---- Schema-driven UI page (pages/schema-ui.tsx) ----
+  'schemaUi.heading':       'Schema-driven UI',
+  'schemaUi.intro':         'The same notes as <a>the home page</a> — but the form + table here are <strong>bound to descriptors</strong>, not hand-wired. Fields come from <code>notes.create</code>’s input schema; columns from <code>notes.list</code>’s output schema. Live + optimistic, zero glue.',
+  'schemaUi.createHeading': 'Create (bound to <code>notes.create</code>)',
+  'schemaUi.listHeading':   'List (bound to <code>notes.list</code>)',
+  'schemaUi.submitLabel':   'Add note',
+  'schemaUi.emptyText':     'No notes yet — add one above.',
+} as const)

package/templates/apps/frontend-app/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-app/src/pages/index.test.tsx

@@ -0,0 +1,167 @@
+// @vitest-environment jsdom
+//
+// `/` — the reactive notes page. It binds `useSubscription('app','notes.list')`
+// + `useMutation('app','notes.create')` from @voltro/client. We mock that module
+// so the render is deterministic and assert the observable output: loading /
+// empty / list states, optimistic-row styling, subscription-error banner, and
+// the submit path calling create.mutate with the trimmed title + body + tenant.
+
+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 SubState {
+  data: unknown
+  revision?: number
+  emittedAt?: number
+  error?: unknown
+  pendingPatches?: number
+}
+
+const useSubscription = vi.fn<() => SubState>()
+const mutate = vi.fn<(input: unknown) => Promise<unknown>>()
+const useMutation = vi.fn(() => ({ mutate, pending: false, error: undefined, data: undefined }))
+
+vi.mock('@voltro/client', () => ({
+  useSubscription: (...a: unknown[]) => useSubscription(...(a as [])),
+  useMutation: (...a: unknown[]) => useMutation(...(a as [])),
+}))
+
+const { default: IndexPage } = 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>/useTFn, so it needs an <I18nProvider>. Wrap with the real
+// English catalog (the framework auto-wires this provider 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 }),
+    )
+  })
+}
+
+const setInput = (el: HTMLInputElement | HTMLTextAreaElement, value: string): void => {
+  const proto =
+    el instanceof window.HTMLTextAreaElement
+      ? window.HTMLTextAreaElement.prototype
+      : window.HTMLInputElement.prototype
+  const setter = Object.getOwnPropertyDescriptor(proto, 'value')!.set!
+  act(() => {
+    setter.call(el, value)
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+  })
+}
+
+beforeEach(() => {
+  useSubscription.mockReset()
+  mutate.mockReset()
+  mutate.mockResolvedValue(undefined)
+  useMutation.mockClear()
+  useMutation.mockReturnValue({ mutate, pending: false, error: undefined, data: undefined })
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — subscription states', () => {
+  test('shows the loading hint before the first snapshot (data undefined)', () => {
+    useSubscription.mockReturnValue({ data: undefined, revision: -1 })
+    render(createElement(IndexPage))
+    expect(container.textContent).toContain('loading…')
+    expect(container.querySelectorAll('li')).toHaveLength(0)
+  })
+
+  test('shows the empty state once a snapshot arrives with no rows', () => {
+    useSubscription.mockReturnValue({ data: [], revision: 0 })
+    render(createElement(IndexPage))
+    expect(container.textContent).toContain('No notes yet')
+  })
+
+  test('renders each note with its title and body', () => {
+    useSubscription.mockReturnValue({
+      data: [
+        { id: 'n_1', title: 'first', body: 'body one', done: false, tenantId: 'acme', createdAt: new Date(0) },
+        { id: 'n_2', title: 'second', body: '', done: false, tenantId: 'acme', createdAt: new Date(0) },
+      ],
+      revision: 3,
+    })
+    render(createElement(IndexPage))
+    const items = Array.from(container.querySelectorAll('li'))
+    expect(items).toHaveLength(2)
+    expect(container.textContent).toContain('first')
+    expect(container.textContent).toContain('body one')
+    expect(container.textContent).toContain('second')
+  })
+
+  test('renders optimistic rows faintly + italicised', () => {
+    useSubscription.mockReturnValue({
+      data: [
+        { id: 'n_opt', title: 'pending', body: '', done: false, tenantId: 'acme', createdAt: new Date(0), optimistic: true },
+      ],
+      revision: 1,
+      pendingPatches: 1,
+    })
+    render(createElement(IndexPage))
+    const li = container.querySelector('li')!
+    expect(li.style.opacity).toBe('0.5')
+    expect(li.style.fontStyle).toBe('italic')
+    expect(container.textContent).toContain('1 pending')
+  })
+
+  test('renders the subscription error banner when error is set', () => {
+    useSubscription.mockReturnValue({ data: undefined, error: 'boom', revision: -1 })
+    render(createElement(IndexPage))
+    expect(container.textContent).toContain('subscription error')
+    expect(container.textContent).toContain('boom')
+  })
+})
+
+describe('index — create form', () => {
+  test('the Add button is disabled until a non-empty title is typed', () => {
+    useSubscription.mockReturnValue({ data: [], revision: 0 })
+    render(createElement(IndexPage))
+    const button = container.querySelector('button[type="submit"]') as HTMLButtonElement
+    expect(button.disabled).toBe(true)
+    setInput(container.querySelector('input') as HTMLInputElement, 'a note')
+    expect(button.disabled).toBe(false)
+  })
+
+  test('submitting calls create.mutate with the trimmed title + body + tenant, then clears', async () => {
+    useSubscription.mockReturnValue({ data: [], revision: 0 })
+    render(createElement(IndexPage))
+    const input = container.querySelector('input') as HTMLInputElement
+    const textarea = container.querySelector('textarea') as HTMLTextAreaElement
+    setInput(input, '  my title  ')
+    setInput(textarea, '  my body  ')
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+    })
+    expect(mutate).toHaveBeenCalledWith({ tenantId: 'acme', title: 'my title', body: 'my body' })
+    expect(input.value).toBe('')
+    expect(textarea.value).toBe('')
+  })
+
+  test('a whitespace-only title does not fire a mutation', async () => {
+    useSubscription.mockReturnValue({ data: [], revision: 0 })
+    render(createElement(IndexPage))
+    setInput(container.querySelector('input') as HTMLInputElement, '   ')
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+    })
+    expect(mutate).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,136 @@
+// `/` — the notes page. Auto-mapped from src/pages/index.tsx by the
+// framework's file-convention page discovery.
+//
+// THIS is the reactive end-to-end loop. `useSubscription('app',
+// 'notes.list')` opens a live WebSocket subscription to the api's
+// `notes.list` query; `useMutation('app', 'notes.create')` invokes the
+// `notes.create` mutation. When the mutation commits, the server pushes a
+// delta and this list re-renders — no refetch, no polling.
+//
+// Auto-optimistic: `notes.create` declares `target: { table: 'notes', op:
+// 'insert' }` server-side, so the framework prepends an optimistic row to
+// this subscription the instant you submit — and replaces it with the real
+// row (or reverts it) when the rpc resolves. There is no `.withOptimistic`,
+// no `useOptimistic`, no `startTransition` — just `create.mutate(input)`.
+
+import { useMutation, useSubscription } from '@voltro/client'
+import { useState, type FormEvent, type ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useTFn } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+// Locale-aware tab title: @voltro/web resolves meta({ locale }) from the
+// active locale (the `voltro:lang` cookie in this cookie-i18n app).
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.notes.title'],
+})
+
+// The dev AuthMiddleware resolves the tenant from the `x-tenant` header,
+// defaulting to 'acme'. The `notes` table carries the `tenant()` mixin, so
+// reads are auto-scoped to this tenant and `notes.create` guards that the
+// submitted tenantId matches the caller's (a typed TenantMismatch otherwise).
+const TENANT = 'acme'
+
+interface Note {
+  readonly id: string
+  readonly title: string
+  readonly body: string
+  readonly done: boolean
+  readonly tenantId: string
+  readonly createdAt: Date
+  readonly optimistic?: boolean
+}
+
+const IndexPage = (): ReactNode => {
+  const { data, revision, emittedAt, error, pendingPatches } =
+    useSubscription<ReadonlyArray<Note>>('app', 'notes.list')
+
+  const create = useMutation<{ tenantId: string; title: string; body: string }>('app', 'notes.create')
+  const t = useTFn()
+
+  const notes = data ?? []
+  const [title, setTitle] = useState('')
+  const [body, setBody] = useState('')
+
+  const handleSubmit = async (event: FormEvent) => {
+    event.preventDefault()
+    const trimmedTitle = title.trim()
+    if (trimmedTitle.length === 0) return
+    setTitle('')
+    setBody('')
+    try {
+      await create.mutate({ tenantId: TENANT, title: trimmedTitle, body: body.trim() })
+    } catch (mutationError) {
+      // notes.create can fail with a typed TenantMismatch; surface it however
+      // your UI prefers. The optimistic row auto-reverts on failure.
+      console.error('notes.create failed:', mutationError)
+    }
+  }
+
+  return (
+    <section>
+      <h1 style={{ fontSize: 24, marginBottom: 4 }}><T id="notes.heading" /></h1>
+      <p style={{ color: '#666', marginTop: 0, fontSize: 13 }}>
+        <T
+          id="notes.status.tenant"
+          values={{ tenant: TENANT, revision, code: (c: ReactNode) => <code>{c}</code> }}
+        />
+        {emittedAt ? (
+          <T id="notes.status.delta" values={{ time: new Date(emittedAt).toLocaleTimeString() }} />
+        ) : null}
+        {pendingPatches > 0 && <T id="notes.status.pending" values={{ count: pendingPatches }} />}
+        {data === undefined && error === undefined && <T id="notes.status.loading" />}
+      </p>
+
+      {error !== undefined && (
+        <p style={{ color: '#c00', fontSize: 13 }}>
+          <T id="notes.error" values={{ error: String(error) }} />
+        </p>
+      )}
+
+      <form onSubmit={handleSubmit} style={{ display: 'grid', gap: 8, margin: '16px 0' }}>
+        <input
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+          placeholder={t('notes.field.title')}
+          style={{ padding: '6px 10px', fontSize: 14 }}
+        />
+        <textarea
+          value={body}
+          onChange={(event) => setBody(event.target.value)}
+          placeholder={t('notes.field.body')}
+          rows={2}
+          style={{ padding: '6px 10px', fontSize: 14, resize: 'vertical' }}
+        />
+        <button type="submit" disabled={title.trim().length === 0 || create.pending} style={{ justifySelf: 'start' }}>
+          {create.pending ? t('notes.adding') : t('notes.add')}
+        </button>
+      </form>
+
+      {notes.length === 0 && data !== undefined && (
+        <p style={{ color: '#999' }}><T id="notes.empty" /></p>
+      )}
+
+      <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'grid', gap: 8 }}>
+        {notes.map((note) => (
+          <li
+            key={note.id}
+            style={{
+              border: '1px solid #eee',
+              borderRadius: 6,
+              padding: '10px 12px',
+              // Optimistic rows (not yet confirmed by the server) render faintly.
+              opacity: note.optimistic ? 0.5 : 1,
+              fontStyle: note.optimistic ? 'italic' : 'normal',
+            }}
+          >
+            <strong>{note.title}</strong>
+            {note.body && <p style={{ margin: '4px 0 0', color: '#444', fontSize: 14 }}>{note.body}</p>}
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}
+
+export default IndexPage

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

@@ -0,0 +1,41 @@
+// Root layout that wraps every page in this app. `<html>` / `<head>` /
+// `<body>` are owned by the framework's index.html shell — don't render
+// them here. Use a page's `meta` export for title + meta tags, and
+// `theme: 'dark' | 'light' | 'system'` in app.config.ts for the dark class.
+//
+// The app is bilingual (see `locales` in app.config.ts): nav labels come from
+// the catalog via `<T>`, and <LocaleSwitcher> writes the `voltro:lang` cookie
+// + reloads so the framework re-renders in the chosen language.
+
+import type { ReactNode } from 'react'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+
+interface LayoutProps {
+  readonly children: ReactNode
+}
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export default function Layout({ children }: LayoutProps): ReactNode {
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  return (
+    <div style={{ maxWidth: 640, margin: '0 auto', padding: '24px 16px', fontFamily: 'system-ui, sans-serif' }}>
+      <header style={{ display: 'flex', gap: 16, alignItems: 'baseline', marginBottom: 24 }}>
+        <strong style={{ fontSize: 16 }}>{{capProjectName}}</strong>
+        {/* Internal <a>s are SPA-intercepted by the Router (no full reload). */}
+        <nav style={{ display: 'flex', gap: 12, fontSize: 13 }}>
+          <a href="/"><T id="nav.notes" /></a>
+          <a href="/schema-ui"><T id="nav.schemaUi" /></a>
+        </nav>
+        <span style={{ color: '#999', fontSize: 12, marginLeft: 'auto' }}><T id="nav.tagline" /></span>
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+      </header>
+      <main>{children}</main>
+    </div>
+  )
+}

package/templates/apps/frontend-app/src/pages/schema-ui.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+//
+// `/schema-ui` — the schema-driven-UI twin of the notes page. It binds
+// <AutoForm> to the `notes.create` mutation and <DataTable> to the `notes.list`
+// query, with title + body Fields. The real AutoForm/DataTable need a live
+// framework runtime; here we mock them (from @voltro/web) as prop-recording
+// sentinels and assert the page passes the right descriptor bindings + defaults.
+
+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 AutoFormProps {
+  api: string
+  mutation: string
+  defaults?: Record<string, unknown>
+  submitLabel?: string
+  children?: () => ReactNode
+}
+interface DataTableProps {
+  api: string
+  query: string
+  emptyText?: string
+}
+
+const autoFormProps: AutoFormProps[] = []
+const dataTableProps: DataTableProps[] = []
+
+vi.mock('@voltro/web', () => ({
+  AutoForm: (props: AutoFormProps) => {
+    autoFormProps.push(props)
+    return createElement('div', { 'data-testid': 'auto-form' }, props.children?.())
+  },
+  DataTable: (props: DataTableProps) => {
+    dataTableProps.push(props)
+    return createElement('div', { 'data-testid': 'data-table' })
+  },
+  Field: ({ name }: { name: string }) =>
+    createElement('span', { 'data-testid': `field-${name}` }, name),
+}))
+
+const { default: SchemaUiPage } = await import('./schema-ui')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>/useTFn, so it needs an <I18nProvider> (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 }),
+    )
+  })
+}
+
+beforeEach(() => {
+  autoFormProps.length = 0
+  dataTableProps.length = 0
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('schema-ui — descriptor bindings', () => {
+  test('binds AutoForm to notes.create with the tenant default + title & body Fields', () => {
+    render(createElement(SchemaUiPage))
+    expect(autoFormProps).toHaveLength(1)
+    expect(autoFormProps[0]).toMatchObject({
+      api: 'app',
+      mutation: 'notes.create',
+      defaults: { tenantId: 'acme', done: false },
+    })
+    expect(container.querySelector('[data-testid="field-title"]')).toBeTruthy()
+    expect(container.querySelector('[data-testid="field-body"]')).toBeTruthy()
+  })
+
+  test('binds DataTable to the notes.list query with empty text', () => {
+    render(createElement(SchemaUiPage))
+    expect(dataTableProps).toHaveLength(1)
+    expect(dataTableProps[0]).toMatchObject({ api: 'app', query: 'notes.list' })
+    expect(dataTableProps[0]!.emptyText).toContain('No notes yet')
+  })
+
+  test('renders the Schema-driven UI heading', () => {
+    render(createElement(SchemaUiPage))
+    const headings = Array.from(container.querySelectorAll('h1,h2')).map((h) => h.textContent)
+    expect(headings.some((h) => h?.includes('Schema-driven UI'))).toBe(true)
+  })
+})

package/templates/apps/frontend-app/src/pages/schema-ui.tsx

@@ -0,0 +1,74 @@
+// `/schema-ui` — the SAME notes as `/` (index.tsx), but rendered by the
+// schema-driven UI components instead of hand-wired hooks. index.tsx wires
+// useSubscription + useMutation + form state by hand (the reactive baseline);
+// this page binds <DataTable> to `notes.list` and <AutoForm> to `notes.create`.
+// The columns + fields come straight from the descriptors' effect/Schema, and
+// validation, live updates, and auto-optimistic come for free — no glue code.
+//
+// Delete this page if you don't need it; it's here to show the binding.
+
+import { AutoForm, DataTable, Field } from '@voltro/web'
+import type { PageMeta } from '@voltro/web'
+import type { ReactNode } from 'react'
+import { T, useTFn } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+const TENANT = 'acme'
+
+// Locale-aware tab title (cookie-i18n — @voltro/web hands meta the active locale).
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.schemaUi.title'],
+})
+
+const SchemaUiPage = (): ReactNode => {
+  const t = useTFn()
+  return (
+    <section style={{ display: 'grid', gap: '1.5rem' }}>
+      <header>
+        <h1 style={{ fontSize: 24, marginBottom: 4 }}><T id="schemaUi.heading" /></h1>
+        <p style={{ color: '#666', marginTop: 0, fontSize: 13 }}>
+          <T
+            id="schemaUi.intro"
+            values={{
+              a: (c: ReactNode) => <a href="/">{c}</a>,
+              strong: (c: ReactNode) => <strong>{c}</strong>,
+              code: (c: ReactNode) => <code>{c}</code>,
+            }}
+          />
+        </p>
+      </header>
+
+      <div>
+        <h2 style={{ fontSize: 16 }}>
+          <T id="schemaUi.createHeading" values={{ code: (c: ReactNode) => <code>{c}</code> }} />
+        </h2>
+        {/* Rung 3 — own the layout: show title + body; tenantId is a default. */}
+        <AutoForm
+          api="app"
+          mutation="notes.create"
+          defaults={{ tenantId: TENANT, done: false }}
+          submitLabel={t('schemaUi.submitLabel')}
+        >
+          {() => (
+            <>
+              <Field name="title" />
+              <Field name="body" />
+            </>
+          )}
+        </AutoForm>
+      </div>
+
+      <div>
+        <h2 style={{ fontSize: 16 }}>
+          <T id="schemaUi.listHeading" values={{ code: (c: ReactNode) => <code>{c}</code> }} />
+        </h2>
+        {/* Columns inferred from the query's output schema; rows are a live
+            subscription that updates on every notes.create. Add a `rowActions`
+            prop once your api defines a per-row mutation (e.g. notes.delete). */}
+        <DataTable api="app" query="notes.list" emptyText={t('schemaUi.emptyText')} />
+      </div>
+    </section>
+  )
+}
+
+export default SchemaUiPage

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-app",
+  "kind": "web",
+  "summary": "The reactive end-to-end loop — a web frontend wired to an api. A live notes list (useSubscription) + a create form (useMutation) with zero-boilerplate auto-optimistic updates. Pairs with api-backend: scaffold both with `create-project --api=api-backend --web=frontend-app`.",
+  "tags": ["web", "frontend", "fullstack", "reactive", "subscription", "mutation", "optimistic", "api-backend"]
+}

package/templates/apps/frontend-app/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-blank/README.md

@@ -0,0 +1,18 @@
+# {{projectName}} / {{appName}}
+
+Voltro web app scaffold (template: **frontend-blank**).
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:5173
+```
+
+## Routing
+
+File-based. `src/pages/index.tsx` mounts at `/`. Add more `*.tsx`
+files in `src/pages/` to create routes. See AGENTS.md for the
+naming rules (`[id]`, `[...slug]`, `(group)`, `error.tsx`,
+`not-found.tsx`, etc.).