@voltro/cli 0.1.0

package/templates/apps/frontend-ssr-api/src/locales/de.ts

@@ -0,0 +1,20 @@
+// 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 (`{count}`, `{queryCall}`) 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':       '{count} Notizen — {{capProjectName}}',
+  'meta.home.description': 'Bei jeder Anfrage serverseitig aus der API gerendert.',
+
+  'lang.label': 'Sprache',
+
+  'home.badge':   'renderMode: ssr · aus der API gespeist',
+  'home.heading': 'Notizen',
+  'home.lead':    'Diese Zeilen stehen im serverseitig gerenderten HTML — der Loader hat sie mit {queryCall} aus der API geholt, bevor die Seite gesendet wurde. Danach übernimmt <code>useSubscription</code> für Live-Updates.',
+  'home.empty':   'Noch keine Notizen. Erstelle eine über die API (ihre <code>notes.create</code>-Mutation), aktualisiere, und sie steht im SSR-HTML.',
+  'home.done':    '✓ erledigt',
+})

package/templates/apps/frontend-ssr-api/src/locales/en.ts

@@ -0,0 +1,31 @@
+// Base catalog — the source of truth for this app's UI strings. Every key here
+// MUST be mirrored in `de.ts`; `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 and rich tags like
+// `<code>…</code>` (rendered by passing a matching function to
+// `<T values={{ code: (c) => <code>{c}</code> }} />`). A code snippet that
+// itself contains `{`/`}` (e.g. `query('notes.list', {})`) is passed as a
+// ReactNode value (`{queryCall}`) — NOT written into the message — so ICU never
+// tries to parse its braces.
+
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  // Tab title + description. `meta.home.title` is a plain lookup with a
+  // `{count}` token substituted in `meta({ loaderData })` (NOT ICU-formatted),
+  // and `{{capProjectName}}` is a scaffold token — both are fine here.
+  'meta.home.title':       '{count} notes — {{capProjectName}}',
+  'meta.home.description': 'Server-rendered from the api on every request.',
+
+  // ---- Layout shell (pages/layout.tsx) ----
+  'lang.label': 'Language',
+
+  // ---- Home page (pages/index.tsx) ----
+  'home.badge':   'renderMode: ssr · fed by the api',
+  'home.heading': 'Notes',
+  'home.lead':    'These rows are in the server-rendered HTML — the loader fetched them from the api with {queryCall} before the page was sent. Then <code>useSubscription</code> takes over for live updates.',
+  'home.empty':   'No notes yet. Create one against the api (its <code>notes.create</code> mutation), refresh, and it’s in the SSR HTML.',
+  'home.done':    '✓ done',
+} as const)

package/templates/apps/frontend-ssr-api/src/locales/index.ts

@@ -0,0 +1,16 @@
+// Catalog lookup OUTSIDE React — for the page's `meta({ locale, loaderData })`
+// locale-aware <title> / <meta description>. 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-ssr-api/src/pages/index.test.tsx

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+//
+// `/` SSR-fed-by-the-api page. The loader pulls `notes.list` from the api's
+// rpc via the server-only `query` fn; `meta` is a function of the loader data
+// so the <title> reflects the real row count. The component renders the SSR'd
+// snapshot, then upgrades to `useSubscription` on the client. We mock
+// `@voltro/web` (loader hook) + `@voltro/client` (subscription).
+
+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 useSubscription = vi.fn<() => { data: unknown }>()
+vi.mock('@voltro/web', () => ({ useLoaderData: () => loaderData() }))
+vi.mock('@voltro/client', () => ({ useSubscription: () => useSubscription() }))
+
+const { default: Home, meta, loader, renderMode } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+interface Note { id: string; title: string; body: string; done: boolean }
+
+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()
+  useSubscription.mockReset()
+  useSubscription.mockReturnValue({ data: undefined })
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+const sample: ReadonlyArray<Note> = [
+  { id: 'n_1', title: 'First note', body: 'hello', done: false },
+  { id: 'n_2', title: 'Second note', body: '', done: true },
+]
+
+describe('index — loader', () => {
+  test('drains `notes.list` from the api via the server-side query fn', async () => {
+    const query = vi.fn(async () => sample)
+    const data = await loader({ query } as never)
+    expect(query).toHaveBeenCalledWith('notes.list', {})
+    expect(data.notes).toEqual(sample)
+  })
+
+  test('returns an empty list when no server-side query fn is present (client nav)', async () => {
+    const data = await loader({ query: undefined } as never)
+    expect(data.notes).toEqual([])
+  })
+})
+
+describe('index — meta', () => {
+  test('bakes the row count into the <title>', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en', loaderData: { notes: sample } }).title).toContain('2 notes')
+  })
+})
+
+describe('index — render', () => {
+  test('renders the SSR snapshot rows when the subscription has no data yet', () => {
+    loaderData.mockReturnValue({ notes: sample })
+    render(createElement(Home))
+    const items = Array.from(container.querySelectorAll('li'))
+    expect(items).toHaveLength(2)
+    expect(container.textContent).toContain('First note')
+    expect(container.textContent).toContain('✓ done')
+  })
+
+  test('the live subscription data overrides the SSR snapshot once connected', () => {
+    loaderData.mockReturnValue({ notes: sample })
+    useSubscription.mockReturnValue({
+      data: [{ id: 'n_9', title: 'Live note', body: '', done: false }],
+    })
+    render(createElement(Home))
+    const items = Array.from(container.querySelectorAll('li'))
+    expect(items).toHaveLength(1)
+    expect(container.textContent).toContain('Live note')
+  })
+
+  test('shows the empty state when there are no notes', () => {
+    loaderData.mockReturnValue({ notes: [] })
+    render(createElement(Home))
+    expect(container.textContent).toContain('No notes yet')
+  })
+})

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

@@ -0,0 +1,83 @@
+// `/` — `renderMode: 'ssr'`, fed by the sibling api. This is the SSR-from-a-
+// real-backend pattern: the loader runs server-side per request and pulls
+// rows from the api BEFORE the HTML is sent, so the first paint + the
+// <title> reflect real data (crawlable, no client round-trip). The component
+// then upgrades the same data to live with `useSubscription`.
+
+import type { ReactNode } from 'react'
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+
+// The row shape `notes.list` streams. Kept local so the page is
+// self-contained — you can also `import type { Note }` from the api's
+// generated types (a type-only cross-app import is browser-safe).
+interface Note {
+  readonly id: string
+  readonly title: string
+  readonly body: string
+  readonly done: boolean
+}
+
+interface HomeData {
+  readonly notes: ReadonlyArray<Note>
+}
+
+export const renderMode = 'ssr' as const
+
+// `query` is present ONLY server-side (ssr/isr). It invokes the api's rpc
+// directly over POST /rpc, forwarding the request's session cookie so the
+// SAME Subject + tenant resolve as the WS path. A streaming query is drained
+// to its FIRST snapshot — here, the current notes for this tenant. Pass the
+// row type so the result is typed without importing the api.
+export const loader: LoaderFn<HomeData> = async ({ query }) => ({
+  notes: query ? await query<ReadonlyArray<Note>>('notes.list', {}) : [],
+})
+
+// `meta` as a function of the loader data AND the active locale → the <title>
+// reflects real api data (SEO + social cards) in the visitor's language. It's a
+// plain catalog lookup (not ICU-formatted), so the row count is substituted
+// into the `{count}` token by hand.
+export const meta = ({ locale, loaderData }: { readonly locale: string; readonly loaderData: HomeData }): PageMeta => ({
+  title:       getCatalog(locale)['meta.home.title'].replace('{count}', String(loaderData.notes.length)),
+  description: getCatalog(locale)['meta.home.description'],
+})
+
+export default function Home(): ReactNode {
+  // The SSR'd snapshot from the loader — correct on first paint.
+  const { notes: initial } = useLoaderData<HomeData>()
+  // Live data once the WebSocket connects. `data` is `undefined` during SSR,
+  // so the server renders `initial` and the client upgrades to `live` on connect.
+  const { data: live } = useSubscription<ReadonlyArray<Note>>('app', 'notes.list')
+  const notes = live ?? initial
+  const code = (c: ReactNode) => <code>{c}</code>
+
+  return (
+    <section>
+      <span className="badge"><T id="home.badge" /></span>
+      <h1><T id="home.heading" /></h1>
+      <p className="lead">
+        <T
+          id="home.lead"
+          values={{ code, queryCall: <code>{"query('notes.list', {})"}</code> }}
+        />
+      </p>
+      {notes.length === 0 ? (
+        <p className="empty">
+          <T id="home.empty" values={{ code }} />
+        </p>
+      ) : (
+        <ul className="notes">
+          {notes.map((note) => (
+            <li key={note.id}>
+              <span className="title">{note.title}</span>{' '}
+              {note.done ? <span className="done"><T id="home.done" /></span> : null}
+              {note.body ? <p className="body">{note.body}</p> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  )
+}

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

@@ -0,0 +1,28 @@
+// Root layout. Loads the stylesheet; the page provides the content.
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+//
+// 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'
+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 (
+    <div className="shell">
+      <header style={{ display: 'flex', justifyContent: 'flex-end', marginBottom: '1rem' }}>
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+      </header>
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-ssr-api",
+  "kind": "web",
+  "summary": "Server-rendered pages fed by a sibling api — an `ssr` loader calls `ctx.query` over the api's POST /rpc so real rows are in the first paint and the <title>, then `useSubscription` upgrades the same data to live. Pairs with api-backend.",
+  "tags": ["web", "frontend", "ssr", "rpc", "fullstack", "seo"]
+}

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

@@ -0,0 +1,49 @@
+# {{projectName}} / {{appName}}
+
+Bilingual (en/de) static SSG blog (template: **frontend-static-blog**).
+Every page is pre-rendered at build time — no server, no per-request
+rendering — once PER LOCALE: English at the bare path, German under `/de`.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev     # dev server with HMR
+```
+
+## What this template demonstrates
+
+| Concept | Where |
+|---|---|
+| `renderMode = 'static'` (pre-render at build) | every page |
+| `interactive = 'none'` (strip ALL JS) | `src/pages/index.tsx` |
+| `interactive = 'islands'` (hydrate one widget) | `src/pages/blog/[slug].tsx` |
+| `island()` + `hydrate: 'load'` strategy | `src/components/ReadingProgress.island.tsx` |
+| `getStaticPaths` (enumerate dynamic routes) | `src/pages/blog/[slug].tsx` |
+| `loader` + `useLoaderData<T>()` | `src/pages/blog/[slug].tsx` |
+| `meta` as a function of loader data (per-post SEO) | `src/pages/blog/[slug].tsx` |
+| A swappable content source (the "CMS") | `src/content/posts.ts` |
+| Bilingual URL-prefix i18n (en + `/de`) | `src/lib/locale.ts`, `src/locales/{en,de}.ts` |
+| `[locale]` mirror pages (per-locale SSG) | `src/pages/[locale]/**` |
+| Cross-product `getStaticPaths` (locale × slug) | `src/pages/[locale]/blog/[slug].tsx` |
+
+## Build + serve
+
+```bash
+pnpm --filter @{{projectName}}/{{appName}} build    # → dist/ (one HTML file per post)
+pnpm --filter @{{projectName}}/{{appName}} start    # serve dist/ locally
+```
+
+Because the output is pure static files, you can also push `dist/` to a
+cheap CDN instead of running a server:
+
+```bash
+voltro static deploy --host cloudflare-pages --project-name {{appName}}
+```
+
+## Adding posts
+
+Append to the array in `src/content/posts.ts`. `getStaticPaths` reads
+the same array, so a new entry is pre-rendered on the next build — no
+route config. In a real app, replace that array with a CMS / database /
+filesystem read; nothing else changes.

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

@@ -0,0 +1,34 @@
+// Web app for the {{projectName}} project — a BILINGUAL (en/de) STATIC blog.
+//
+// Every page declares `renderMode = 'static'`, so `voltro build`
+// pre-renders flat HTML at build time and `voltro start` (or any CDN
+// via `voltro static deploy`) serves it with zero per-request work.
+// `port` is allocated by the scaffolder from the project's portRange.
+//
+// Strategy B (URL-prefix i18n): the default locale lives at the bare path
+// (`/`, `/blog/…`) and every other locale is prefixed (`/de`, `/de/blog/…`).
+// `locales` is load-bearing — it tells `voltro build` to pre-render a
+// per-locale HTML variant for every `[locale]/…` mirror page, each wrapped
+// in the right catalog's <I18nProvider>. Cookie i18n can't translate a
+// zero-hydration static page, so the URL strategy is the only one that works
+// here. Every code listed MUST have a matching `src/locales/<code>.ts`. Keep
+// this in sync with SUPPORTED_LOCALES / DEFAULT_LOCALE in src/lib/locale.ts.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Public, build-time env (baked into the bundle; read via `publicEnv`).
+// Never a secret here — a static site has no server to hide one.
+export const env = defineEnv({
+  VOLTRO_PUBLIC_SITE_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  // Follow the visitor's OS theme, set before first paint (no flash).
+  theme: 'system' as const,
+  // The shipped catalogs. `defaultLocale` MUST be one of `locales`.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  env,
+}

package/templates/apps/frontend-static-blog/package.json

@@ -0,0 +1,28 @@
+{
+  "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": {
+    "@voltro/cli": "0.1.0",
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/i18n": "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-static-blog/src/components/ReadingProgress.island.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+//
+// The <ReadingProgress> island — a scroll-driven progress bar. We mock
+// `@voltro/web`'s `island()` to the identity so the default export IS the raw
+// component, then assert it renders the progress-bar element and recomputes its
+// width on scroll.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ComponentType, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+
+vi.mock('@voltro/web', () => ({
+  island: (Component: ComponentType<unknown>) => Component,
+}))
+
+const { default: ReadingProgress } = await import('./ReadingProgress.island')
+
+;(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(node)
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('ReadingProgress island', () => {
+  test('renders the progress-bar element, hidden from assistive tech', () => {
+    render(createElement(ReadingProgress))
+    const bar = container.querySelector('.reading-progress') as HTMLElement
+    expect(bar).not.toBeNull()
+    expect(bar.getAttribute('aria-hidden')).toBe('true')
+  })
+
+  test('starts at 0% when the document is not scrollable', () => {
+    render(createElement(ReadingProgress))
+    const bar = container.querySelector('.reading-progress') as HTMLElement
+    // jsdom reports scrollHeight === clientHeight (0), so max <= 0 → 0%.
+    expect(bar.style.width).toBe('0%')
+  })
+
+  test('recomputes width to 100% at the bottom of a scrollable document', () => {
+    render(createElement(ReadingProgress))
+    const el = document.documentElement
+    Object.defineProperty(el, 'scrollHeight', { value: 2000, configurable: true })
+    Object.defineProperty(el, 'clientHeight', { value: 1000, configurable: true })
+    Object.defineProperty(el, 'scrollTop', { value: 1000, configurable: true })
+    act(() => {
+      window.dispatchEvent(new Event('scroll'))
+    })
+    const bar = container.querySelector('.reading-progress') as HTMLElement
+    expect(bar.style.width).toBe('100%')
+  })
+})

package/templates/apps/frontend-static-blog/src/components/ReadingProgress.island.tsx

@@ -0,0 +1,35 @@
+// An ISLAND: a single interactive widget hydrated inside an otherwise-static
+// page. The blog post page is `interactive: 'islands'`, so the framework
+// renders the article once and attaches React ONLY to this component — the
+// surrounding HTML never runs a React lifecycle.
+//
+// `hydrate: 'load'` wakes it immediately (it must track scrolling from the
+// first frame). Other strategies: 'idle', 'visible' (on scroll-into-view),
+// 'interaction' (on first pointer/key), 'never' (inert HTML forever).
+
+import type { ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+import { island } from '@voltro/web'
+
+function ReadingProgress(): ReactNode {
+  const [pct, setPct] = useState(0)
+
+  useEffect(() => {
+    const onScroll = (): void => {
+      const el = document.documentElement
+      const max = el.scrollHeight - el.clientHeight
+      setPct(max > 0 ? Math.min(100, (el.scrollTop / max) * 100) : 0)
+    }
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    window.addEventListener('resize', onScroll)
+    return () => {
+      window.removeEventListener('scroll', onScroll)
+      window.removeEventListener('resize', onScroll)
+    }
+  }, [])
+
+  return <div className="reading-progress" style={{ width: `${pct}%` }} aria-hidden="true" />
+}
+
+export default island(ReadingProgress, { name: 'ReadingProgress', hydrate: 'load' })

package/templates/apps/frontend-static-blog/src/content/posts.ts

@@ -0,0 +1,64 @@
+// The content source for the blog.
+//
+// This is a plain in-repo array — the simplest stand-in for a CMS. In a
+// real app, swap the body of `getStaticPaths` + the page loader to read
+// from your CMS / database / filesystem instead. NOTHING else changes:
+// the build still pre-renders one HTML file per entry.
+//
+// Because this module is imported by both the index page (the list) and
+// the [slug] page (the detail) AND by `getStaticPaths`, it is the single
+// source of truth for "which posts exist".
+
+export interface Post {
+  /** URL segment — `/blog/<slug>`. Must be unique + DNS-safe. */
+  readonly slug: string
+  readonly title: string
+  /** ISO date, shown + used for ordering. */
+  readonly date: string
+  /** One-line summary — feeds the list + the `<meta name="description">`. */
+  readonly excerpt: string
+  readonly readingMinutes: number
+  /** Body paragraphs, separated by a blank line. */
+  readonly body: string
+}
+
+export const posts: ReadonlyArray<Post> = [
+  {
+    slug: 'hello-static',
+    title: 'Why this blog ships zero JavaScript',
+    date: '2025-01-15',
+    excerpt: 'Every page is pre-rendered at build time, so the browser downloads HTML and nothing else.',
+    readingMinutes: 3,
+    body: `This page was rendered ONCE, when you ran \`voltro build\`. The result is a flat \`dist/blog/hello-static/index.html\` that any CDN can serve in single-digit milliseconds.
+
+There is no server rendering per request, no React hydration on the list page, no rpc client on the wire. The list page even declares \`interactive = 'none'\`, which strips every \`<script>\` the framework would otherwise emit.
+
+When you DO need a sprinkle of interactivity — a reading-progress bar, a copy button, a comment box — you reach for an island instead of hydrating the whole tree. Read the next post for how that works.`,
+  },
+  {
+    slug: 'islands-not-hydration',
+    title: 'Islands: hydrate the 5% that moves',
+    date: '2025-01-22',
+    excerpt: 'A static page with one interactive widget should ship one widget of JavaScript — not the whole page.',
+    readingMinutes: 4,
+    body: `Look at the top of this page: a thin progress bar tracks how far you have scrolled. That bar is an ISLAND — a single component the framework hydrates inside otherwise-static HTML.
+
+This page declares \`interactive = 'islands'\`, so the framework renders the article once and only attaches React to the \`island()\`-wrapped component. The surrounding HTML has zero React lifecycle running.
+
+Each island picks WHEN it wakes up via a hydrate strategy: \`load\` (immediately), \`idle\`, \`visible\` (on scroll-into-view), or \`interaction\` (on first click). The progress bar uses \`load\` because it must track scrolling from the very first frame.
+
+The lesson: don't default to \`islands\` because it sounds fast. Use it when most of the page is static and only a few widgets move. A dashboard where everything is interactive wants \`full\` hydration instead.`,
+  },
+  {
+    slug: 'cms-to-ssg',
+    title: 'From CMS to static pages with getStaticPaths',
+    date: '2025-02-03',
+    excerpt: 'Enumerate your content once; the build emits one pre-rendered page per entry.',
+    readingMinutes: 3,
+    body: `A dynamic route like \`src/pages/blog/[slug].tsx\` matches infinitely many URLs. To pre-render it statically, the build needs to know WHICH slugs exist — that is what \`getStaticPaths\` answers.
+
+In this template, \`getStaticPaths\` maps over the \`posts\` array in \`src/content/posts.ts\`. Point it at a CMS API, a database query, or a folder of markdown files instead, and the build will pre-render exactly those pages — the Next.js "static generation from a content source" pattern, with no extra config.
+
+URLs you do not enumerate simply are not built. If a page ALSO sets \`renderMode = 'ssr' | 'isr'\`, \`voltro start\` renders the un-enumerated ones on demand; a pure \`'static'\` page 404s for unknown slugs, which is exactly what you want for a fixed content set.`,
+  },
+]

package/templates/apps/frontend-static-blog/src/globals.css

@@ -0,0 +1,75 @@
+/* Self-contained styles — plain CSS, no Tailwind / no kit dependency, so
+ * this template builds with nothing but @voltro/web. Swap in
+ * @voltro/ui-shadcn/tokens.css if you want the design system. */
+
+:root {
+  --bg: #ffffff;
+  --fg: #18181b;
+  --muted: #71717a;
+  --accent: #7c3aed;
+  --border: #e4e4e7;
+  --maxw: 42rem;
+}
+
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #a1a1aa;
+  --accent: #a78bfa;
+  --border: #27272a;
+}
+
+* { box-sizing: border-box; }
+
+html, body { margin: 0; min-height: 100vh; }
+
+body {
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+main {
+  max-width: var(--maxw);
+  margin: 0 auto;
+  padding: 3rem 1.25rem 6rem;
+}
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+h1 { font-size: 2rem; line-height: 1.2; margin: 0 0 0.5rem; }
+h2 { font-size: 1.1rem; margin: 0; }
+
+.site-header {
+  display: flex;
+  align-items: center;
+  border-bottom: 1px solid var(--border);
+  padding: 1rem 1.25rem;
+}
+.site-header .brand { color: var(--fg); font-weight: 600; }
+.site-header .spacer { flex: 1; }
+.site-header .lang { display: flex; gap: 0.5rem; align-items: center; font-size: 0.85rem; }
+.site-header .lang .label { color: var(--muted); }
+.site-header .lang a { color: var(--fg); font-weight: 400; }
+.site-header .lang a[aria-current='true'] { color: var(--accent); font-weight: 600; }
+
+.muted { color: var(--muted); font-size: 0.9rem; }
+
+.post-list { list-style: none; padding: 0; margin: 2rem 0 0; }
+.post-list li { padding: 1.25rem 0; border-bottom: 1px solid var(--border); }
+.post-list a { font-size: 1.25rem; font-weight: 600; color: var(--fg); }
+.post-list p { margin: 0.35rem 0 0; color: var(--muted); }
+
+article p { margin: 1.1rem 0; }
+
+/* The reading-progress island — a fixed bar pinned to the top. */
+.reading-progress {
+  position: fixed;
+  top: 0;
+  left: 0;
+  height: 3px;
+  background: var(--accent);
+  transition: width 80ms linear;
+  z-index: 50;
+}