@voltro/cli 0.28.0 → 0.30.0

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

@@ -0,0 +1,62 @@
+// The editor shell — and the AUTH GATE. This layout wraps every page in the
+// silent `(app)` group (URLs `/`), and its `loader` runs server-side BEFORE the
+// pages render: it asks the api who the caller is (`session.me`) and throws
+// RedirectError to /login for anyone not signed in. The pages under here are
+// `renderMode: 'ssr'` precisely so this runs per request.
+import type { ReactNode } from 'react'
+import { RedirectError, useLoaderData, type LoaderFn } from '@voltro/web'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import type { Identity } from '../../lib/api'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+interface AppData {
+  readonly tenantId: string | null
+}
+
+export const loader: LoaderFn<AppData> = async ({ query }) => {
+  // `query` is present ONLY server-side (the SSR full-page load). There, ask the
+  // api's `session.me` — it forwards the request's session cookie — and bounce
+  // an anonymous caller to /login.
+  if (query) {
+    const me = await query<Identity>('session.me', {})
+    if (me.type !== 'user') {
+      throw new RedirectError('/login?from=/')
+    }
+    return { tenantId: me.tenantId }
+  }
+  // Client navigation: the entry load already gated; every rpc is independently
+  // session-authed on the server (the HttpOnly cookie isn't readable in JS).
+  return { tenantId: null }
+}
+
+export default function AppLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  useLoaderData<AppData>()
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+
+  const signOut = (): void => {
+    void fetch('/auth/csrf')
+      .then((r) => r.json() as Promise<{ csrfToken: string }>)
+      .then((c) =>
+        fetch('/auth/sign-out', { method: 'POST', headers: { 'x-csrf-token': c.csrfToken } }),
+      )
+      .finally(() => window.location.assign('/login'))
+  }
+
+  return (
+    <div className="cms">
+      <header className="cms-top">
+        <span className="brand"><T id="editor.brand" /></span>
+        <span className="spacer" />
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+        <button type="button" className="link" onClick={signOut}><T id="editor.signOut" /></button>
+      </header>
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,14 @@
+// Scoped 404 for the editor subtree. Fires when a URL under the group matches no
+// page, and when a loader throws NotFoundError.
+import type { ReactNode } from 'react'
+import { T } from '@voltro/i18n'
+
+export default function EditorNotFound(): ReactNode {
+  return (
+    <main style={{ padding: '2rem' }}>
+      <h1><T id="notFound.heading" /></h1>
+      <p className="muted"><T id="notFound.body" /></p>
+      <p style={{ marginTop: '1rem' }}><a href="/"><T id="notFound.back" /></a></p>
+    </main>
+  )
+}

package/templates/apps/frontend-cms/src/pages/(app)/page.test.tsx

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+//
+// The editor page. We mock `@voltro/client` (content.types fetch, the live list,
+// the save mutation) and drive it: after the types load the page renders a type
+// chip + an auto-generated <ContentForm> (real, from @voltro/cms/web), and a
+// save that comes back `{ ok: false, violations }` annotates the form inline
+// rather than throwing.
+
+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 blogType = {
+  name: 'blogPost', displayName: 'Blog post', pluralName: 'Blog posts',
+  columns: ['title', 'slug', 'status'],
+  fields: [
+    { name: 'title', kind: 'string', editorHint: 'text', isOptional: false },
+    { name: 'body', kind: 'richText', editorHint: 'richText', isOptional: false },
+  ],
+}
+
+const typesRun = vi.fn<() => Promise<{ types: unknown }>>()
+const getRun = vi.fn<() => Promise<{ row: unknown }>>()
+const saveMutate = vi.fn<(input: unknown) => Promise<unknown>>()
+const subData = vi.fn<() => { data: unknown }>()
+
+vi.mock('@voltro/client', () => ({
+  useAction: (_api: string, tag: string) => ({
+    run: tag === 'content.types' ? typesRun : getRun,
+    pending: false,
+  }),
+  useMutation: (_api: string, tag: string) => ({
+    mutate: tag === 'content.saveDraft' ? saveMutate : vi.fn().mockResolvedValue({ ok: true }),
+    pending: false,
+  }),
+  useSubscription: () => subData(),
+}))
+
+const { default: Editor, meta, renderMode } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+// Flush the mount-effect fetch (typesRun.then → setState) + its re-render.
+const flush = async (): Promise<void> => {
+  await act(async () => { await Promise.resolve(); await Promise.resolve() })
+}
+
+beforeEach(() => {
+  typesRun.mockReset(); typesRun.mockResolvedValue({ types: [blogType] })
+  getRun.mockReset(); getRun.mockResolvedValue({ row: null })
+  saveMutate.mockReset(); saveMutate.mockResolvedValue({ ok: true, id: 'blogPost_1', status: 'draft' })
+  subData.mockReset(); subData.mockReturnValue({ data: [] })
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('editor — config', () => {
+  test('is an SSR page titled Content (so the parent gate runs per request)', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Content')
+  })
+})
+
+describe('editor — render', () => {
+  test('after the types load, renders the type chip and an auto-generated form', async () => {
+    render(createElement(Editor))
+    await flush()
+    expect(typesRun).toHaveBeenCalled()
+    expect(container.textContent).toContain('Blog post')
+    // <ContentForm> renders one [data-cms-field] per declared field.
+    expect(container.querySelectorAll('[data-cms-field]').length).toBe(2)
+    expect(container.querySelector('[data-cms-field="title"]')).not.toBeNull()
+  })
+})
+
+describe('editor — validation', () => {
+  test('a save that returns { ok: false, violations } annotates the form', async () => {
+    saveMutate.mockResolvedValue({ ok: false, violations: [{ field: 'title', rule: 'required', message: 'missing required field' }] })
+    render(createElement(Editor))
+    await flush()
+    const form = container.querySelector('form')!
+    await act(async () => {
+      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+      await Promise.resolve(); await Promise.resolve()
+    })
+    expect(saveMutate).toHaveBeenCalled()
+    expect(container.querySelector('.violations')).not.toBeNull()
+    expect(container.textContent).toContain('missing required field')
+  })
+})

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

@@ -0,0 +1,159 @@
+// The editor — URL `/`. Introspects the api's registered content types
+// (`content.types`) and generates a form per type with @voltro/cms's
+// `<ContentForm>`; lists a type's drafts live (`content.list`), saves them
+// (`content.saveDraft`, with per-field validation surfaced inline), and
+// publishes / unpublishes them. One page, no dynamic routes — the selected type
+// and the row being edited are component state.
+import type { ReactNode } from 'react'
+import { useEffect, useMemo, useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useAction, useMutation, useSubscription } from '@voltro/client'
+import { ContentForm } from '@voltro/cms/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+import {
+  toContentFormType,
+  type ContentRow,
+  type ContentTypeDescriptor,
+  type SaveResult,
+} from '../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.editor.title'],
+})
+
+interface Violation { readonly field: string; readonly rule: string; readonly message: string }
+
+export default function Editor(): ReactNode {
+  const types = useAction<Record<string, never>, { types: ReadonlyArray<ContentTypeDescriptor> }>(
+    'cms', 'content.types',
+  )
+  const getOne = useAction<{ type: string; id: string; status: string }, { row: Record<string, unknown> | null }>(
+    'cms', 'content.get',
+  )
+  const save = useMutation<{ type: string; values: Record<string, unknown> }, SaveResult>('cms', 'content.saveDraft')
+  const publish = useMutation<{ type: string; id: string }, { ok: boolean }>('cms', 'content.publish')
+  const unpublish = useMutation<{ type: string; id: string }, { ok: boolean }>('cms', 'content.unpublish')
+
+  const [typeList, setTypeList] = useState<ReadonlyArray<ContentTypeDescriptor>>([])
+  const [active, setActive] = useState<string | null>(null)
+  const [values, setValues] = useState<Record<string, unknown>>({})
+  const [editingId, setEditingId] = useState<string | null>(null)
+  const [violations, setViolations] = useState<ReadonlyArray<Violation>>([])
+  const [saved, setSaved] = useState(false)
+
+  // Load the content types once; select the first.
+  useEffect(() => {
+    void types.run({}).then((r) => {
+      setTypeList(r.types)
+      setActive((cur) => cur ?? r.types[0]?.name ?? null)
+    })
+  }, []) // mount-only fetch of the content-type descriptors
+
+  const activeType = typeList.find((t) => t.name === active) ?? null
+
+  // Live drafts of the active type. Memoised input so a stable object identity
+  // avoids resubscribing every render; an unset/unknown type yields an empty list.
+  const listInput = useMemo(() => ({ type: active ?? '—', status: 'draft' as const }), [active])
+  const { data: rows } = useSubscription<ReadonlyArray<ContentRow>>('cms', 'content.list', listInput)
+  const drafts = rows ?? []
+
+  const resetForm = (): void => { setValues({}); setEditingId(null); setViolations([]) }
+
+  const onSelectType = (name: string): void => { setActive(name); resetForm(); setSaved(false) }
+
+  const onEdit = (id: string): void => {
+    if (active === null) return
+    void getOne.run({ type: active, id, status: 'draft' }).then((r) => {
+      if (r.row) { setValues(r.row); setEditingId(id); setViolations([]); setSaved(false) }
+    })
+  }
+
+  const onSubmit = (e: FormEvent): void => {
+    e.preventDefault()
+    if (active === null) return
+    const payload = editingId ? { ...values, id: editingId } : values
+    void save.mutate({ type: active, values: payload }).then((res) => {
+      if (res.ok) { resetForm(); setSaved(true) } else { setViolations(res.violations); setSaved(false) }
+    })
+  }
+
+  const onPublish = (id: string): void => { if (active) void publish.mutate({ type: active, id }) }
+  const onUnpublish = (id: string): void => { if (active) void unpublish.mutate({ type: active, id }) }
+
+  const statusKey = (s: string): 'editor.status.draft' | 'editor.status.published' | 'editor.status.archived' =>
+    s === 'published' ? 'editor.status.published' : s === 'archived' ? 'editor.status.archived' : 'editor.status.draft'
+
+  if (typeList.length === 0) {
+    return <section className="cms-main"><p className="empty"><T id="editor.form.loading" /></p></section>
+  }
+
+  return (
+    <div className="cms-grid">
+      {/* Left: type chooser + live draft list */}
+      <section className="cms-list">
+        <h2 className="label"><T id="editor.types.heading" /></h2>
+        <nav className="cms-types">
+          {typeList.map((t) => (
+            <button
+              key={t.name} type="button"
+              className={t.name === active ? 'chip active' : 'chip'}
+              onClick={() => onSelectType(t.name)}
+            >
+              {t.displayName}
+            </button>
+          ))}
+        </nav>
+
+        <h3 className="label" style={{ marginTop: '1rem' }}>
+          <T id="editor.list.heading" values={{ type: activeType?.pluralName ?? '' }} />
+        </h3>
+        {drafts.length === 0 ? (
+          <p className="empty"><T id="editor.list.empty" /></p>
+        ) : (
+          <ul className="rows">
+            {drafts.map((row) => (
+              <li key={row.id}>
+                <span className="grow">{row.title ?? row.slug ?? row.id}</span>
+                <span className="tag"><T id={statusKey(row.status)} /></span>
+                <button type="button" className="link" onClick={() => onEdit(row.id)}><T id="editor.row.edit" /></button>
+                <button type="button" className="link" onClick={() => onPublish(row.id)}><T id="editor.row.publish" /></button>
+                <button type="button" className="link" onClick={() => onUnpublish(row.id)}><T id="editor.row.unpublish" /></button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      {/* Right: the auto-generated form */}
+      <section className="cms-editor">
+        <h2>
+          {editingId
+            ? <T id="editor.form.editing" />
+            : <T id="editor.form.new" values={{ type: activeType?.displayName ?? '' }} />}
+        </h2>
+        {activeType ? (
+          <form onSubmit={onSubmit}>
+            <ContentForm contentType={toContentFormType(activeType)} value={values} onChange={setValues} />
+            {violations.length > 0 ? (
+              <ul className="violations" role="alert">
+                {violations.map((v) => <li key={v.field + v.rule}>{v.field}: {v.message}</li>)}
+              </ul>
+            ) : null}
+            {saved ? <p className="ok"><T id="editor.form.saved" /></p> : null}
+            <div className="row" style={{ marginTop: '0.75rem' }}>
+              <button type="submit" className="btn" disabled={save.pending}>
+                <T id={save.pending ? 'editor.form.saving' : 'editor.form.save'} />
+              </button>
+              {editingId ? (
+                <button type="button" className="btn ghost" onClick={resetForm}><T id="editor.form.cancel" /></button>
+              ) : null}
+            </div>
+          </form>
+        ) : null}
+      </section>
+    </div>
+  )
+}

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

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

package/templates/apps/frontend-cms/src/pages/login/page.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+//
+// The auth form. We assert config + that it renders email/password fields and
+// toggles between sign-in and sign-up. The network submit (CSRF + POST /auth/*)
+// is exercised against a running api by `voltro dev`, not unit-mocked here.
+
+import { afterEach, describe, expect, test } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../locales/en'
+
+const { default: Login, meta, renderMode } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('login — config', () => {
+  test('is a static page titled Sign in', () => {
+    expect(renderMode).toBe('static')
+    expect(meta({ locale: 'en' }).title).toBe('Sign in')
+  })
+})
+
+describe('login — form', () => {
+  test('renders email + password inputs and defaults to sign-in', () => {
+    render(createElement(Login))
+    expect(container.querySelector('input[type="email"]')).not.toBeNull()
+    expect(container.querySelector('input[type="password"]')).not.toBeNull()
+    expect(container.querySelector('h1')?.textContent).toBe('Sign in to the CMS')
+  })
+
+  test('toggling switches to the create-account heading', () => {
+    render(createElement(Login))
+    const toggle = container.querySelector('.link')!
+    act(() => { toggle.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    expect(container.querySelector('h1')?.textContent).toBe('Create an editor account')
+  })
+})

package/templates/apps/frontend-cms/src/pages/login/page.tsx

@@ -0,0 +1,93 @@
+// Sign in / sign up — URL `/login`. A REAL auth form: it POSTs to the api's
+// `/auth/*` routes (contributed by @voltro/plugin-auth on api-cms), which set
+// the HttpOnly session cookie. State-changing auth routes are CSRF-protected, so
+// we fetch a token first. On success we do a FULL navigation so the editor's SSR
+// gate re-runs with the freshly-set cookie.
+import type { ReactNode } from 'react'
+import { useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.login.title'],
+})
+
+type Mode = 'signIn' | 'signUp'
+
+async function submitAuth(mode: Mode, email: string, password: string): Promise<boolean> {
+  const csrf = (await fetch('/auth/csrf').then((r) => r.json())) as { csrfToken: string }
+  const path = mode === 'signUp' ? '/auth/sign-up' : '/auth/sign-in'
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-csrf-token': csrf.csrfToken },
+    body: JSON.stringify({ email, password }),
+  })
+  return res.ok
+}
+
+export default function Login(): ReactNode {
+  const [mode, setMode] = useState<Mode>('signIn')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [pending, setPending] = useState(false)
+  const [failed, setFailed] = useState(false)
+  const emailLabel = useT('auth.email')
+  const passwordLabel = useT('auth.password')
+
+  const onSubmit = (e: FormEvent): void => {
+    e.preventDefault()
+    setPending(true)
+    setFailed(false)
+    void submitAuth(mode, email, password)
+      .then((ok) => {
+        if (ok) {
+          const from = new URLSearchParams(window.location.search).get('from') ?? '/'
+          window.location.assign(from)
+        } else {
+          setFailed(true)
+          setPending(false)
+        }
+      })
+      .catch(() => {
+        setFailed(true)
+        setPending(false)
+      })
+  }
+
+  return (
+    <section className="hero">
+      <h1><T id={mode === 'signUp' ? 'auth.signUp.heading' : 'auth.signIn.heading'} /></h1>
+      <form className="auth-form" onSubmit={onSubmit}>
+        <label>
+          <span><T id="auth.email" /></span>
+          <input
+            type="email" required aria-label={emailLabel} value={email}
+            onChange={(e) => setEmail(e.target.value)}
+          />
+        </label>
+        <label>
+          <span><T id="auth.password" /></span>
+          <input
+            type="password" required aria-label={passwordLabel} value={password}
+            onChange={(e) => setPassword(e.target.value)}
+          />
+        </label>
+        {failed ? <p className="error-text"><T id="auth.error" /></p> : null}
+        <button type="submit" className="btn" disabled={pending}>
+          <T id={pending ? 'auth.pending' : mode === 'signUp' ? 'auth.signUp.submit' : 'auth.signIn.submit'} />
+        </button>
+      </form>
+      <p style={{ marginTop: '1rem' }}>
+        <button
+          type="button" className="link"
+          onClick={() => { setMode((m) => (m === 'signIn' ? 'signUp' : 'signIn')); setFailed(false) }}
+        >
+          <T id={mode === 'signIn' ? 'auth.toggle.toSignUp' : 'auth.toggle.toSignIn'} />
+        </button>
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-cms",
+  "kind": "web",
+  "summary": "The CMS editor UI for the api-cms backend: a sign-in page (POST /auth/*), an SSR auth gate (session.me → redirect anonymous editors to /login), and a content editor that fetches the registered content types (content.types) and auto-generates a form per type with @voltro/cms's <ContentForm> — create/edit drafts (content.saveDraft, validation surfaced inline), live-list them (content.list), and publish/unpublish. Bilingual (en/de).",
+  "tags": ["web", "frontend", "cms", "editor", "content", "auth", "ssr", "ContentForm"]
+}

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

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,80 @@
+# {{projectName}} / {{appName}}
+
+Voltro collaborative-editing frontend (template: **frontend-collab**).
+
+A document editor whose textarea is bound to a `crdtText()` body over the
+framework's reactive loop. Type in **two browser tabs at once** and the edits
+**converge** — no last-write-wins loser — because the api merges every update
+into the shared document server-side, then broadcasts the merged result back
+live. Zero infra: the merge and the broadcast are in-process on a single
+`voltro dev`.
+
+## Scaffold the pair
+
+`frontend-collab` consumes a sibling api — scaffold it **together with
+[`api-collab`](../api-collab)** (which exposes the `documents.list` subscription
++ `documents.create` / `documents.setBody` mutations):
+
+```bash
+voltro create-project collab --api=api-collab --web=frontend-collab
+cd collab
+pnpm install
+pnpm dev            # boots BOTH apps (api on :4000, web on its portRange port)
+```
+
+Open the web app, click **Create document**, then open a **second tab** on the
+same URL and type in both. Every keystroke merges — both tabs' edits survive.
+
+## How it works
+
+```
+ Tab A                              api (api-collab)
+ ─────                              ────────────────
+ local crdtText() handle           documents.setBody (crdtText 'body' column)
+   │  keystroke → insert/delete       └─ runtime folds the update into the
+   │  → handle.encode()  ──rpc──►        STORED state (mergeCrdtStates) → merged
+   ▼                                        └─► reactive delta ──WS──► every tab
+ useSubscription('app',
+   'documents.list')  ◄──WS── merged body ── handle.merge(body) → textarea
+```
+
+1. **`useSubscription('app', 'documents.list')`** streams the shared document,
+   including its **merged** `body` (encoded CRDT bytes), on every write.
+2. A **local `crdtText()` handle** (`@voltro/local-first`) is seeded from that
+   body. Each keystroke applies a contiguous insert/delete to the handle and
+   sends `handle.encode()` via **`useMutation('app', 'documents.setBody')`**.
+3. The api's **authoritative server-side merge** folds the update into the
+   stored state before broadcasting — so concurrent edits converge.
+4. Incoming server bodies are **folded back** into the local handle
+   (idempotent), keeping every tab in sync.
+
+This page is exactly the app-level binding the local-first docs describe as the
+`SyncClient` transport: `push` = the `setBody` mutation, `onRemoteState` = the
+`documents` subscription.
+
+## Not wired here: presence cursors
+
+Live "who else is editing" cursors (`usePresence` from
+`@voltro/local-first/react`) need a `PresenceChannel` bound to the app's
+broadcast broker — a runtime binding, not zero-infra in a single dev process
+across tabs — so this template omits them. The CRDT text convergence above needs
+none of that; it rides the reactive engine you already have.
+
+## Files
+
+```
+app.config.ts            type:web + the `apis: { app }` wiring
+package.json             depends on @{{projectName}}/api (the sibling) + @voltro/local-first
+src/pages/
+  layout.tsx             root shell (header + <main>)
+  page.tsx               the collaborative editor — subscription + CRDT handle + setBody
+  page.test.tsx          render + edit-dispatch tests (jsdom)
+src/locales/{en,de}.ts   bilingual UI strings
+```
+
+## Multi-tenancy note
+
+The dev `AuthMiddleware` resolves the tenant from the `x-tenant` header,
+defaulting to `'acme'` (the `TENANT` constant in `page.tsx`). The `documents`
+table carries the `tenant()` mixin, so reads/writes are auto-scoped. Wire real
+auth before production (see the authentication docs).

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

@@ -0,0 +1,38 @@
+// Web app for the {{projectName}} project. Read by `voltro dev` / `voltro start`.
+//
+// This is the COLLABORATIVE-EDITING frontend — a textarea bound to a
+// `crdtText()` document body over the framework's reactive loop. Open it in two
+// browser tabs and type in both: the edits CONVERGE (no last-write-wins loser)
+// because the api's server-authoritative CRDT merge folds every update into the
+// stored state, then the reactive engine broadcasts the merged row back. Zero
+// infra — the merge + broadcast are in-process on a single `voltro dev`.
+//
+// `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).
+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()` work app-wide.
+  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', 'documents.list')`, `useMutation('app',
+  // 'documents.setBody')`. The `package` resolves the sibling api in this
+  // project (scaffold it with `--api=api-collab`).
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}