@voltro/cli 0.1.0

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

@@ -0,0 +1,29 @@
+// Web app for the {{projectName}} project. Read by `voltro dev` / `voltro start`.
+//
+// `port` is allocated by `voltro create-project` / `voltro add-app` from
+// the project's portRange (in project.json). Hard-pinned per app; the
+// dev server fails fast on conflicts instead of silently incrementing.
+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'
+// (typed, autocompleted). NEVER put a secret here (it would ship 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,
+}

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

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@voltro/cli": "0.1.0",
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/i18n": "0.1.0",
+    "@voltro/ui-shadcn": "0.1.0",
+    "@voltro/web": "0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

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

@@ -0,0 +1,15 @@
+// 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 and rich tags (`<code>`) identical to `en.ts`.
+
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.home.title': 'Startseite',
+
+  'lang.label': 'Sprache',
+
+  'home.intro':
+    'Bearbeite <code>src/pages/index.tsx</code>, um loszulegen. Lege weitere <code>*.tsx</code>-Dateien in <code>src/pages/</code> ab, um Routen hinzuzufügen — ganz ohne Router-Konfiguration.',
+})

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

@@ -0,0 +1,22 @@
+// 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 title — locale-aware via the page's `meta({ locale })`.
+  'meta.home.title': 'Home',
+
+  // ---- Layout shell (pages/layout.tsx) ----
+  'lang.label': 'Language',
+
+  // ---- Index page (pages/index.tsx) ----
+  'home.intro':
+    'Edit <code>src/pages/index.tsx</code> to start building. Drop more <code>*.tsx</code> files in <code>src/pages/</code> to add routes — no router config required.',
+} as const)

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

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+//
+// `/` — the blank starter's single page. A pure static component with no
+// hooks, loader, or meta; we mount it and assert its observable structure
+// (the heading element + the "start building" copy + the src/pages hint).
+// The heading text itself carries a `{{capProjectName}}` scaffold placeholder,
+// so we assert the <h1> EXISTS rather than pinning its substituted text.
+
+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'
+
+import Index from './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>. 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 }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — render', () => {
+  test('renders a top-level heading inside a <main>', () => {
+    render(createElement(Index))
+    const main = container.querySelector('main')
+    expect(main).toBeTruthy()
+    expect(main!.querySelector('h1')).toBeTruthy()
+  })
+
+  test('shows the getting-started hint pointing at src/pages/index.tsx', () => {
+    render(createElement(Index))
+    expect(container.textContent).toContain('Edit')
+    const codes = Array.from(container.querySelectorAll('code')).map((c) => c.textContent)
+    expect(codes).toContain('src/pages/index.tsx')
+  })
+})

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

@@ -0,0 +1,27 @@
+// Mounted at `/`. The router maps `src/pages/<file>.tsx` to `/<file>`
+// — see AGENTS.md for the conventions (groups, [param], [...slug]).
+//
+// Bilingual by default: the copy comes from the catalog via `<T>` (see
+// src/locales), and <LocaleSwitcher> in the layout switches language.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T } 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.home.title'],
+})
+
+export default function Index(): ReactNode {
+  return (
+    <main>
+      <h1>{{capProjectName}}</h1>
+      <p>
+        <T id="home.intro" values={{ code: (c: ReactNode) => <code>{c}</code> }} />
+      </p>
+    </main>
+  )
+}

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

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+//
+// Root layout — renders a language switcher in the header, then its children
+// (no <html>/<head>/<body>, which the framework shell owns). We assert the
+// children render, the <LocaleSwitcher> is present, and no document element is
+// introduced. The layout uses <LocaleSwitcher> + useLocale/useT, so we wrap the
+// render in the real <I18nProvider> (the framework auto-wires it in the app).
+
+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'
+
+import Layout from './layout'
+
+;(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('layout — render', () => {
+  test('renders its children and the language switcher', () => {
+    render(
+      createElement(Layout, { children: createElement('span', { 'data-testid': 'child' }, 'hi') }),
+    )
+    const child = container.querySelector('[data-testid="child"]')
+    expect(child).toBeTruthy()
+    expect(child!.textContent).toBe('hi')
+    expect(container.querySelector('select[aria-label]')).toBeTruthy()
+  })
+
+  test('does not introduce a document element (html/head/body)', () => {
+    render(createElement(Layout, { children: createElement('p', {}, 'body content') }))
+    expect(container.querySelector('html, head, body')).toBeNull()
+  })
+})

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

@@ -0,0 +1,35 @@
+// Root layout that wraps every page in this app. Add nav, providers,
+// error boundaries, etc. here. `<html>` / `<head>` / `<body>` are
+// owned by the framework's index.html shell — don't render them here
+// or the browser will unwrap them under #root and the document
+// structure breaks. Use the page's `meta` export for title + meta
+// tags, and `theme: 'dark' | 'light' | 'system'` in app.config.ts
+// to control the dark class.
+//
+// The app is bilingual (see `locales` in app.config.ts): <LocaleSwitcher>
+// writes the `voltro:lang` cookie + reloads so the framework re-renders in
+// the chosen language.
+
+import type { ReactNode } from 'react'
+import { 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 {
+  return (
+    <>
+      <header style={{ display: 'flex', justifyContent: 'flex-end', padding: '12px 16px' }}>
+        <LocaleSwitcher locales={LOCALES} current={useLocale()} ariaLabel={useT('lang.label')} />
+      </header>
+      {children}
+    </>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-blank",
+  "kind": "web",
+  "summary": "Empty React + Vite frontend with a layout shell and an index page. Starting point for any custom UI.",
+  "tags": ["web", "frontend", "blank", "minimal", "starter"]
+}

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

@@ -0,0 +1,65 @@
+# {{projectName}} / {{appName}}
+
+Static page **+** serverless email form (template: **frontend-contact**) —
+the canonical "static frontend, serverless backend" combo.
+
+- `src/pages/index.tsx` — a static page (`renderMode: 'static'`).
+- `src/components/ContactForm.island.tsx` — the only hydrated part (an island).
+- `functions/sendMessage.serverless.ts` — a standalone serverless function
+  that sends mail via Resend. Deployed SEPARATELY from the page.
+
+## Run it locally (two terminals)
+
+```bash
+pnpm install
+
+# Terminal 1 — the static site (HMR dev server)
+pnpm --filter @{{projectName}}/{{appName}} dev
+
+# Terminal 2 — the serverless function on http://localhost:8910
+pnpm --filter @{{projectName}}/{{appName}} fn:dev
+```
+
+The form POSTs to `http://localhost:8910` (see `src/config.ts`). The function
+answers cross-origin because the framework's runner sends CORS headers — the
+same headers Cloudflare / Scaleway add at the edge.
+
+Without `RESEND_API_KEY` set, the function returns a clean `503
+email-not-configured` and the form shows it — it never pretends to send. To
+send for real:
+
+```bash
+RESEND_API_KEY=re_... CONTACT_TO=you@example.com \
+  pnpm --filter @{{projectName}}/{{appName}} fn:dev
+```
+
+## Deploy
+
+The page and the function ship to **different** places — that's the point.
+
+```bash
+# 1. The static page → a CDN
+pnpm --filter @{{projectName}}/{{appName}} build
+voltro static deploy --host cloudflare-pages --project-name {{appName}}
+
+# 2. The function → a function host (scales to zero)
+cd apps/{{projectName}}/{{appName}}
+voltro serverless deploy --target scaleway --namespace-id <id>
+#   ...or --target cloudflare, or --target node for a self-hosted sidecar
+```
+
+Then point the form at the deployed function: set `CONTACT_ENDPOINT` in
+`src/config.ts` to the URL `voltro serverless deploy` printed, and rebuild.
+
+## What this template demonstrates
+
+| Concept | Where |
+|---|---|
+| Static page + selective hydration (`interactive: 'islands'`) | `src/pages/index.tsx` |
+| An island with `hydrate: 'visible'` | `src/components/ContactForm.island.tsx` |
+| A serverless function (`defineServerless`) | `functions/sendMessage.serverless.ts` |
+| Schema-validated input → typed 400 | the function's `input` |
+| Outbound HTTP via `HttpClient` (Resend) | the function's handler |
+| `ServerlessHttpError` to control the status (503 / 502) | the function's handler |
+| Secrets from `ctx.env` (RESEND_API_KEY) | the function's handler |
+| Cross-origin fetch that works locally (CORS) | the runner + the island |

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

@@ -0,0 +1,25 @@
+// Web app for the {{projectName}} project — a STATIC page with a serverless
+// contact form. The page itself is pre-rendered (`renderMode = 'static'`); the
+// form is an island that POSTs to a SEPARATE serverless function
+// (functions/sendMessage.serverless.ts), which you deploy with
+// `voltro serverless`. The page can ship to a CDN; the function scales to zero.
+import { defineEnv, envVar } from '@voltro/env'
+
+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}},
+  theme: 'system' as const,
+  // Bilingual, Strategy B (URL-prefix): English at the bare path, German
+  // under /de. `voltro build` pre-renders a per-locale variant for every
+  // `[locale]/…` mirror page. Keep in sync with SUPPORTED_LOCALES /
+  // DEFAULT_LOCALE in src/lib/locale.ts. Every code listed MUST have a
+  // matching src/locales/<code>.ts or boot fails.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  env,
+}

package/templates/apps/frontend-contact/functions/sendMessage.serverless.ts

@@ -0,0 +1,69 @@
+// The serverless backend for the contact form.
+//
+// A standalone `*.serverless.ts` — it is NOT part of a long-running api. The
+// CLI bundles + ships it on its own:
+//
+//   voltro serverless dev    functions/sendMessage.serverless.ts   # run locally (:8910)
+//   voltro serverless deploy --target node | cloudflare | scaleway # ship it
+//
+// It receives the form payload, validates it against `input`, and sends an
+// email via Resend's HTTP API using the framework-provided `HttpClient`.
+// Edge-safe: no `node:*`, so it also runs on a Cloudflare Worker.
+//
+// Secrets come from `ctx.env` (set at deploy time): RESEND_API_KEY is required;
+// CONTACT_TO / CONTACT_FROM are optional overrides.
+
+import { Effect, Schema } from 'effect'
+import { HttpClient, HttpClientRequest } from '@effect/platform'
+import { defineServerless, ServerlessHttpError } from '@voltro/serverless'
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/
+
+export default defineServerless({
+  name: 'send-message',
+  method: 'POST',
+  input: Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(120)),
+    email: Schema.String.pipe(Schema.pattern(EMAIL_RE)),
+    message: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(5000)),
+  }),
+  output: Schema.Struct({ ok: Schema.Boolean }),
+  runtime: { memoryMb: 128, timeoutSeconds: 10 },
+  handler: ({ name, email, message }, ctx) =>
+    Effect.gen(function* () {
+      const apiKey = ctx.env.RESEND_API_KEY
+      const to = ctx.env.CONTACT_TO ?? 'you@example.com'
+      const from = ctx.env.CONTACT_FROM ?? 'Contact form <onboarding@resend.dev>'
+
+      // No key wired yet → fail with a clear 503 the form can render. The
+      // function never pretends to send: honest in dev, honest in prod.
+      if (!apiKey) {
+        return yield* Effect.fail(
+          new ServerlessHttpError({
+            status: 503,
+            message: 'email-not-configured',
+            detail: 'Set RESEND_API_KEY (+ optionally CONTACT_TO / CONTACT_FROM) in the function env.',
+          }),
+        )
+      }
+
+      const http = yield* HttpClient.HttpClient
+      const request = HttpClientRequest.post('https://api.resend.com/emails').pipe(
+        HttpClientRequest.setHeader('authorization', `Bearer ${apiKey}`),
+        HttpClientRequest.bodyUnsafeJson({
+          from,
+          to: [to],
+          reply_to: email,
+          subject: `New message from ${name}`,
+          text: `${message}\n\n— ${name} <${email}>`,
+        }),
+      )
+
+      const response = yield* http.execute(request)
+      if (response.status >= 400) {
+        const detail = yield* response.text
+        return yield* Effect.fail(new ServerlessHttpError({ status: 502, message: 'email-send-failed', detail }))
+      }
+      return { ok: true }
+    }),
+})

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

@@ -0,0 +1,33 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "fn:dev": "voltro serverless dev functions/sendMessage.serverless.ts",
+    "fn:deploy": "voltro serverless deploy --target node",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/i18n": "0.1.0",
+    "@voltro/serverless": "0.1.0",
+    "@voltro/web": "0.1.0",
+    "effect": "^3.21.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/frontend-contact/src/components/ContactForm.island.test.tsx

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom
+//
+// <ContactForm> — the island inside the static contact page. It POSTs
+// { name, email, message } as JSON to CONTACT_ENDPOINT and reflects the
+// request lifecycle (idle → sending → sent | error). We mock `island` to a
+// passthrough (so the bare component renders without the marker wrapper),
+// pin CONTACT_ENDPOINT, and stub `fetch` to assert the submit payload and the
+// success + error UI transitions.
+//
+// The island is i18n-agnostic: it takes all its UI copy as a `labels` prop
+// (the page resolves it per-locale). We pass the English labels here so the
+// assertions read the same strings the page would supply.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ComponentType, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import type { ContactFormLabels } from './ContactForm.island'
+
+vi.mock('@voltro/web', () => ({
+  // Passthrough: return the component untouched so we test its own behavior,
+  // not the island marker wrapper.
+  island: (Component: ComponentType<unknown>) => Component,
+}))
+
+vi.mock('../config', () => ({ CONTACT_ENDPOINT: 'https://fn.test/contact' }))
+
+const { default: ContactForm } = await import('./ContactForm.island')
+
+// English labels — the same strings the page resolves from the en catalog.
+const labels: ContactFormLabels = {
+  name: 'Name',
+  email: 'Email',
+  message: 'Message',
+  send: 'Send message',
+  sending: 'Sending…',
+  sentNotice: 'Thanks — your message is on its way. ✓',
+  errorPrefix: 'Could not send:',
+  networkError: 'network error',
+}
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+const fetchMock = vi.fn<typeof fetch>()
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(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 }))
+  })
+}
+
+const fill = (): void => {
+  setInput(container.querySelector('#name') as HTMLInputElement, 'Ada')
+  setInput(container.querySelector('#email') as HTMLInputElement, 'ada@example.com')
+  setInput(container.querySelector('#message') as HTMLTextAreaElement, 'hello there')
+}
+
+const submit = async (): Promise<void> => {
+  const form = container.querySelector('form') as HTMLFormElement
+  await act(async () => {
+    form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+  })
+}
+
+beforeEach(() => {
+  fetchMock.mockReset()
+  vi.stubGlobal('fetch', fetchMock)
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+  vi.unstubAllGlobals()
+})
+
+describe('ContactForm — render', () => {
+  test('renders the name/email/message fields and a submit button', () => {
+    render(createElement(ContactForm, { labels }))
+    expect(container.querySelector('#name')).toBeTruthy()
+    expect(container.querySelector('#email')).toBeTruthy()
+    expect(container.querySelector('#message')).toBeTruthy()
+    expect((container.querySelector('button[type="submit"]') as HTMLButtonElement).textContent)
+      .toContain('Send message')
+  })
+})
+
+describe('ContactForm — submit', () => {
+  test('POSTs the form values as JSON to CONTACT_ENDPOINT and shows the sent notice', async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }))
+    render(createElement(ContactForm, { labels }))
+    fill()
+    await submit()
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://fn.test/contact')
+    expect(init?.method).toBe('POST')
+    expect(JSON.parse(init?.body as string)).toEqual({
+      name: 'Ada',
+      email: 'ada@example.com',
+      message: 'hello there',
+    })
+    expect(container.textContent).toContain('on its way')
+  })
+
+  test('surfaces the server error detail when the response is not ok', async () => {
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ detail: 'rate limited' }), { status: 429 }),
+    )
+    render(createElement(ContactForm, { labels }))
+    fill()
+    await submit()
+    expect(container.textContent).toContain('Could not send')
+    expect(container.textContent).toContain('rate limited')
+  })
+
+  test('surfaces a network error when fetch rejects', async () => {
+    fetchMock.mockRejectedValue(new Error('offline'))
+    render(createElement(ContactForm, { labels }))
+    fill()
+    await submit()
+    expect(container.textContent).toContain('Could not send')
+    expect(container.textContent).toContain('offline')
+  })
+})