@voltro/cli 0.1.0

package/templates/apps/frontend-ssr/src/pages/feed-swr.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+//
+// `/feed-swr` ISR + stale-while-revalidate page — its cache config exports,
+// the loader, and the render.
+
+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 loaderData = vi.fn<() => unknown>()
+vi.mock('@voltro/web', () => ({ useLoaderData: () => loaderData() }))
+
+const { default: FeedSwr, meta, loader, renderMode, revalidate, staleWhileRevalidate } =
+  await import('./feed-swr')
+
+;(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> (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(() => {
+  loaderData.mockReset()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('feed-swr — cache config', () => {
+  test('is ISR with both a revalidate and a stale-while-revalidate window', () => {
+    expect(renderMode).toBe('isr')
+    expect(revalidate).toBe('5 seconds')
+    expect(staleWhileRevalidate).toBe('30 seconds')
+    expect(meta({ locale: 'en' }).title).toContain('stale-while-revalidate')
+  })
+})
+
+describe('feed-swr — loader', () => {
+  test('resolves a fresh ISO timestamp + a numeric nonce', async () => {
+    const data = await loader({} as never)
+    expect(Number.isNaN(Date.parse(data.renderedAt))).toBe(false)
+    expect(typeof data.nonce).toBe('number')
+  })
+})
+
+describe('feed-swr — render', () => {
+  test('renders the loader data', () => {
+    loaderData.mockReturnValue({ renderedAt: '2020-01-01T00:00:00.000Z', nonce: 99 })
+    render(createElement(FeedSwr))
+    expect(container.textContent).toContain('2020-01-01T00:00:00.000Z')
+    expect(container.textContent).toContain('99')
+  })
+})

package/templates/apps/frontend-ssr/src/pages/feed-swr.tsx

@@ -0,0 +1,54 @@
+// `/feed-swr` — ISR with `staleWhileRevalidate`. When the `revalidate` window
+// expires, instead of blocking the next visitor on a fresh render, the cache
+// serves the STALE HTML immediately AND kicks off a background re-render. The
+// visitor never waits; the cache catches up out-of-band.
+
+import type { ReactNode } from 'react'
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+export const renderMode = 'isr' as const
+export const revalidate = '5 seconds'
+// Within this window AFTER `revalidate` expires, requests get the STALE HTML
+// instantly + a background refresh runs. Beyond (revalidate + swr) the next
+// request blocks on a fresh render, like plain ISR.
+export const staleWhileRevalidate = '30 seconds'
+
+// Locale-aware tab title + description (cookie-i18n — @voltro/web hands meta
+// the active locale).
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title:       getCatalog(locale)['meta.swr.title'],
+  description: getCatalog(locale)['meta.swr.description'],
+})
+
+interface SwrData {
+  readonly renderedAt: string
+  readonly nonce: number
+}
+
+export const loader: LoaderFn<SwrData> = async () => ({
+  renderedAt: new Date().toISOString(),
+  nonce: Math.floor(Math.random() * 1_000_000),
+})
+
+export default function FeedSwr(): ReactNode {
+  const data = useLoaderData<SwrData>()
+  const code = (c: ReactNode) => <code>{c}</code>
+  return (
+    <section>
+      <span className="badge"><T id="swr.badge" /></span>
+      <h1 style={{ marginTop: '0.75rem' }}><T id="swr.heading" /></h1>
+      <p className="lead"><T id="swr.lead" /></p>
+
+      <ul className="fields">
+        <li><span className="k"><T id="field.renderedAt" /></span><span className="v">{data.renderedAt}</span></li>
+        <li><span className="k"><T id="field.nonce" /></span><span className="v">{data.nonce}</span></li>
+      </ul>
+
+      <p className="note">
+        <T id="swr.note" values={{ code }} />
+      </p>
+    </section>
+  )
+}

package/templates/apps/frontend-ssr/src/pages/feed.test.tsx

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+//
+// `/feed` ISR page — its cache config exports (revalidate, tenantAware), the
+// loader reading the `x-tenant` header, and the render.
+
+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 loaderData = vi.fn<() => unknown>()
+vi.mock('@voltro/web', () => ({ useLoaderData: () => loaderData() }))
+
+const { default: Feed, meta, loader, renderMode, revalidate, tenantAware } = await import('./feed')
+
+;(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> (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(() => {
+  loaderData.mockReset()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('feed — cache config', () => {
+  test('is ISR with a revalidate window and is tenant-aware', () => {
+    expect(renderMode).toBe('isr')
+    expect(revalidate).toBe('10 seconds')
+    expect(tenantAware).toBe(true)
+    expect(meta({ locale: 'en' }).title).toContain('ISR')
+  })
+})
+
+describe('feed — loader', () => {
+  test('reads the tenant from the x-tenant header', async () => {
+    const data = await loader({ headers: { 'x-tenant': 'acme' } } as never)
+    expect(data.tenant).toBe('acme')
+    expect(Number.isNaN(Date.parse(data.renderedAt))).toBe(false)
+  })
+
+  test('falls back to `anonymous` when x-tenant is absent', async () => {
+    const data = await loader({ headers: {} } as never)
+    expect(data.tenant).toBe('anonymous')
+  })
+})
+
+describe('feed — render', () => {
+  test('renders the tenant + nonce from loader data', () => {
+    loaderData.mockReturnValue({ renderedAt: '2020-01-01T00:00:00.000Z', nonce: 7, tenant: 'acme' })
+    render(createElement(Feed))
+    expect(container.textContent).toContain('acme')
+    expect(container.textContent).toContain('7')
+  })
+})

package/templates/apps/frontend-ssr/src/pages/feed.tsx

@@ -0,0 +1,64 @@
+// `/feed` — `renderMode: 'isr'`. Same render path as SSR, but `voltro start`
+// CACHES the HTML and serves the cached copy to every request within the
+// `revalidate` window. After the window expires, the next request re-renders
+// and replaces the cache.
+//
+// Use ISR for content that changes occasionally, is the same for every
+// visitor (or only per-tenant), and is expensive to render (a CMS lookup, a
+// third-party API). Cache hits return in <1ms.
+
+import type { ReactNode } from 'react'
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+export const renderMode = 'isr' as const
+
+// Cache window — a number (seconds) OR a string like '1 hour' / '30 seconds'.
+export const revalidate = '10 seconds'
+
+// Tenant-aware caching: the cache key includes the `x-tenant` request header,
+// so tenant A's render is never served to tenant B. Leave it off for pages
+// that don't vary by tenant (they then share ONE cache entry).
+export const tenantAware = true
+
+// Locale-aware tab title + description (cookie-i18n — @voltro/web hands meta
+// the active locale).
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title:       getCatalog(locale)['meta.isr.title'],
+  description: getCatalog(locale)['meta.isr.description'],
+})
+
+interface FeedData {
+  readonly renderedAt: string
+  readonly nonce: number
+  readonly tenant: string
+}
+
+export const loader: LoaderFn<FeedData> = async ({ headers }) => ({
+  renderedAt: new Date().toISOString(),
+  nonce: Math.floor(Math.random() * 1_000_000),
+  tenant: headers?.['x-tenant'] ?? 'anonymous',
+})
+
+export default function Feed(): ReactNode {
+  const data = useLoaderData<FeedData>()
+  const code = (c: ReactNode) => <code>{c}</code>
+  return (
+    <section>
+      <span className="badge"><T id="isr.badge" /></span>
+      <h1 style={{ marginTop: '0.75rem' }}><T id="isr.heading" /></h1>
+      <p className="lead"><T id="isr.lead" /></p>
+
+      <ul className="fields">
+        <li><span className="k"><T id="field.renderedAt" /></span><span className="v">{data.renderedAt}</span></li>
+        <li><span className="k"><T id="field.nonce" /></span><span className="v">{data.nonce}</span></li>
+        <li><span className="k"><T id="isr.field.tenant" /></span><span className="v">{data.tenant}</span></li>
+      </ul>
+
+      <p className="note">
+        <T id="isr.note" values={{ code }} />
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+//
+// `/` SSR page — its `meta`, its per-request `loader`, and the render reading
+// both the loader data and the incoming request (via useServerRequest). The
+// hooks are backed by a <Router> context in the real app, so we mock
+// `@voltro/web` and drive the data directly.
+
+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 loaderData = vi.fn<() => unknown>()
+const serverRequest = vi.fn<() => unknown>()
+vi.mock('@voltro/web', () => ({
+  useLoaderData: () => loaderData(),
+  useServerRequest: () => serverRequest(),
+}))
+
+const { default: Home, meta, loader, renderMode } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>, so it needs an <I18nProvider>. 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 }),
+    )
+  })
+}
+
+beforeEach(() => {
+  loaderData.mockReset()
+  serverRequest.mockReset()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — config + meta', () => {
+  test('renders per request (ssr) and declares a title', () => {
+    expect(renderMode).toBe('ssr')
+    const m = meta({ locale: 'en' })
+    expect(m.title).toContain('SSR')
+    expect(m.description).toContain('every request')
+  })
+})
+
+describe('index — loader', () => {
+  test('resolves a fresh ISO timestamp + a numeric nonce', async () => {
+    const data = await loader({} as never)
+    expect(Number.isNaN(Date.parse(data.renderedAt))).toBe(false)
+    expect(typeof data.nonce).toBe('number')
+  })
+})
+
+describe('index — render', () => {
+  test('shows the loader data + falls back to `unset` when the request is empty', () => {
+    loaderData.mockReturnValue({ renderedAt: '2020-01-01T00:00:00.000Z', nonce: 42 })
+    serverRequest.mockReturnValue(undefined)
+    render(createElement(Home))
+    expect(container.textContent).toContain('2020-01-01T00:00:00.000Z')
+    expect(container.textContent).toContain('42')
+    expect(container.textContent).toContain('unset')
+  })
+
+  test('surfaces the accept-language header + theme cookie from the request', () => {
+    loaderData.mockReturnValue({ renderedAt: '2020-01-01T00:00:00.000Z', nonce: 1 })
+    serverRequest.mockReturnValue({
+      headers: { 'accept-language': 'de-DE' },
+      cookies: { 'voltro:theme': 'dark' },
+    })
+    render(createElement(Home))
+    expect(container.textContent).toContain('de-DE')
+    expect(container.textContent).toContain('dark')
+  })
+})

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

@@ -0,0 +1,72 @@
+// `/` — `renderMode: 'ssr'`. The loader runs on the SERVER on EVERY request
+// (`voltro start`), so the page is rendered fresh per visit — the timestamp
+// and nonce change on each refresh, and the loader can read the incoming
+// request (cookies, headers) to personalise the HTML before it's sent.
+//
+// Use SSR for anything that varies per request: a logged-in dashboard, a
+// page that reads the visitor's cookie/locale, or any data that must NOT be
+// cached across requests.
+
+import type { ReactNode } from 'react'
+import { useLoaderData, useServerRequest, type LoaderFn, type PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+export const renderMode = 'ssr' as const
+
+// Locale-aware tab title + description: @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.ssr.title'],
+  description: getCatalog(locale)['meta.ssr.description'],
+})
+
+interface HomeData {
+  readonly renderedAt: string
+  readonly nonce: number
+}
+
+// The loader runs server-side per request. `headers` carries the incoming
+// request headers (lowercased). To pull fresh data from YOUR reactive api
+// instead of computing it here, declare an `apis` entry in app.config.ts and:
+//
+//   export const loader: LoaderFn<HomeData> = async ({ query, headers }) => ({
+//     // `query` is present ONLY server-side (ssr/isr). It calls your api's
+//     // rpc directly, forwarding the session cookie — same Subject as the WS.
+//     latest: await query!('posts.latest', {}),
+//   })
+//
+export const loader: LoaderFn<HomeData> = async () => ({
+  renderedAt: new Date().toISOString(),
+  nonce: Math.floor(Math.random() * 1_000_000),
+})
+
+export default function Home(): ReactNode {
+  const data = useLoaderData<HomeData>()
+  // `useServerRequest()` reads the request's cookies + headers — on the
+  // server during SSR, and the same shape on the client. Drive cookie-backed
+  // prefs (locale, theme) with it WITHOUT a hydration flash.
+  const req = useServerRequest()
+  const acceptLanguage = req?.headers['accept-language'] ?? 'unset'
+  const themeCookie = req?.cookies['voltro:theme'] ?? 'unset'
+  const code = (c: ReactNode) => <code>{c}</code>
+
+  return (
+    <section>
+      <span className="badge"><T id="ssr.badge" /></span>
+      <h1 style={{ marginTop: '0.75rem' }}><T id="ssr.heading" /></h1>
+      <p className="lead"><T id="ssr.lead" /></p>
+
+      <ul className="fields">
+        <li><span className="k"><T id="field.renderedAt" /></span><span className="v">{data.renderedAt}</span></li>
+        <li><span className="k"><T id="field.nonce" /></span><span className="v">{data.nonce}</span></li>
+        <li><span className="k"><T id="ssr.field.acceptLanguage" /></span><span className="v">{acceptLanguage}</span></li>
+        <li><span className="k"><T id="ssr.field.themeCookie" /></span><span className="v">{themeCookie}</span></li>
+      </ul>
+
+      <p className="note">
+        <T id="ssr.note" values={{ code }} />
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,37 @@
+// Root layout — nav + globals. These pages hydrate fully (the default for
+// ssr/isr), so internal <a> links do client-side navigation (the Router
+// intercepts them) after the first load.
+//
+// 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'
+import '../globals.css'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  return (
+    <>
+      <nav className="top">
+        {/* Plain <a> — the Router intercepts internal anchors for SPA nav (no
+            full reload), same as the reference templates. */}
+        <a href="/"><T id="nav.ssr" /></a>
+        <a href="/feed"><T id="nav.isr" /></a>
+        <a href="/feed-swr"><T id="nav.swr" /></a>
+        <span style={{ marginLeft: 'auto' }}>
+          <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+        </span>
+      </nav>
+      <main>{children}</main>
+    </>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-ssr",
+  "kind": "web",
+  "summary": "Server-rendered pages — the SSR + ISR render modes. A per-request SSR page (reads cookies/headers via useServerRequest, fresh every visit) plus ISR pages (revalidate, stale-while-revalidate, tenant-aware caching). Self-contained: builds + runs with zero infra; swap the loader for ctx.query to pull from your api.",
+  "tags": ["web", "frontend", "ssr", "isr", "render-mode", "revalidate", "cache", "swr"]
+}

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

@@ -0,0 +1,50 @@
+# {{projectName}} / {{appName}}
+
+Voltro web app scaffold (template: **frontend-ssr-api**) — server-rendered
+pages fed by a sibling api.
+
+## Boot — needs a paired api
+
+This template consumes an api that exposes `notes.list` / `notes.create`.
+Scaffold both:
+
+```bash
+voltro create-project acme --api=api-backend --web=frontend-ssr-api
+pnpm install
+# api in one terminal, web in another:
+pnpm --filter @acme/api dev
+pnpm --filter @acme/web dev      # → http://localhost:{{port}}
+```
+
+## What this shows
+
+- **SSR fed by your backend** — `src/pages/index.tsx` is `renderMode: 'ssr'`.
+  Its loader runs on the server on every request and calls
+  `query('notes.list', {})` over the api's `POST /rpc` surface (forwarding the
+  session cookie, so the same Subject + tenant resolve as the WebSocket path).
+  Real rows are in the **first paint** and the document `<title>` — crawlable,
+  no client round-trip.
+- **`meta` from loader data** — the `<title>` reflects the real note count in
+  the server-rendered HTML (good for SEO + social cards), not a client guess.
+- **SSR → live, one data source** — the component renders the SSR'd snapshot,
+  then `useSubscription('app', 'notes.list')` upgrades it to live once the
+  WebSocket connects (`useSubscription` is `undefined` during SSR, so the
+  first paint is the loader's data; it swaps to live on the client).
+
+## How the pairing resolves
+
+`apis.app.package` in `app.config.ts` points at the sibling api package
+(`@{{projectName}}/api`). The api's port is auto-discovered from its own
+`app.config.ts`, and codegen pulls its typed rpc surface — so `query` and
+`useSubscription` are end-to-end typed against the api's schema.
+
+## SSR vs the other render modes
+
+- This page must hit the api per request → `renderMode: 'ssr'`.
+- If the data changes only occasionally and can be cached, use `'isr'`
+  (`export const revalidate = '5 minutes'`) — same loader, cached HTML.
+- For a fully client-reactive page (no SSR), use `useSubscription` /
+  `useMutation` in a default-mode page — see `frontend-app`.
+
+See AGENTS.md › *Server-side rpc in loaders (`ctx.query`)* for the full
+reference.

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

@@ -0,0 +1,43 @@
+// Web app for the {{projectName}} project — SERVER-RENDERED, fed by a sibling api.
+//
+// The index page is `renderMode: 'ssr'`: its loader runs on the SERVER on
+// every request and calls `ctx.query('notes.list', {})` over the api's
+// POST /rpc surface, so real rows are baked into the FIRST paint + the
+// document <title> — no client round-trip, crawlable, correct for SEO. The
+// component then upgrades the SAME data to live with `useSubscription`.
+//
+// This pairs with an api that exposes `notes.list` — scaffold one with
+// `--api=api-backend`. The `apis.app.package` resolves that sibling api in
+// the project; its port is auto-discovered from its own app.config.ts, and
+// codegen pulls its typed rpc surface so `query` + `useSubscription` are
+// end-to-end typed.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Public, build-time env (baked into the bundle; read via `publicEnv`).
+// Never a secret here — declare secrets on the api.
+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,
+  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 (SSR too) 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
+  // loader's `query` + the hooks use: `query('notes.list', {})`,
+  // `useSubscription('app', 'notes.list')`.
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

package/templates/apps/frontend-ssr-api/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 .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "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"
+  }
+}

package/templates/apps/frontend-ssr-api/src/globals.css

@@ -0,0 +1,38 @@
+/* Plain CSS — no Tailwind, so there's no @source scanner to configure. */
+:root {
+  --bg: #ffffff;
+  --fg: #0a0a0a;
+  --muted: #6b7280;
+  --accent: #4f46e5;
+  --border: #e5e7eb;
+  --panel: #f9fafb;
+}
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #9ca3af;
+  --accent: #818cf8;
+  --border: #1f2937;
+  --panel: #111827;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  line-height: 1.55;
+}
+.shell { max-width: 40rem; margin: 0 auto; padding: 2.5rem 1.25rem; }
+.badge { display: inline-block; font-size: 0.75rem; font-weight: 600; color: var(--accent); background: color-mix(in oklab, var(--accent) 14%, transparent); padding: 0.15rem 0.5rem; border-radius: 999px; }
+h1 { margin: 0.75rem 0 0.25rem; }
+.lead { color: var(--muted); margin-top: 0; }
+ul.notes { list-style: none; padding: 0; margin: 1.5rem 0 0; display: flex; flex-direction: column; gap: 0.6rem; }
+ul.notes li { border: 1px solid var(--border); border-radius: 10px; padding: 0.8rem 1rem; background: var(--panel); }
+ul.notes .title { font-weight: 600; }
+ul.notes .done { color: var(--accent); }
+ul.notes .body { color: var(--muted); font-size: 0.9rem; margin-top: 0.2rem; }
+.empty { color: var(--muted); margin-top: 1.5rem; }
+.muted { color: var(--muted); }
+code { background: color-mix(in oklab, var(--fg) 8%, transparent); padding: 0.1em 0.35em; border-radius: 4px; }

package/templates/apps/frontend-ssr-api/src/globals.d.ts

@@ -0,0 +1,6 @@
+// Ambient declarations.
+//
+// `declare module '*.css'`: TypeScript with `moduleResolution: Bundler`
+// rejects a bare `import './globals.css'` unless the asset module is
+// declared. Vite resolves it at build time; the declaration is type-only.
+declare module '*.css'