@voltro/cli 0.52.0 → 0.54.0

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

@@ -10,8 +10,11 @@ export default defineCatalog({
   'nav.home':     'Home',
   'nav.language': 'Language',
 
-  'hero.tagline': 'Replace this hero copy with your value prop.',
-  'hero.cta':     'Learn more →',
+  'hero.tagline':  'Replace this hero copy with your value prop.',
+  'hero.cta':      'Learn more →',
+  // `alt` is an attribute, so the page reads this with `useT` (a string), not
+  // <T> (an element). Decorative-only images take alt="" instead.
+  'hero.imageAlt': 'Abstract gradient artwork',
 
   'features.heading':     'Features',
   'features.reactive':    '<strong>Reactive subscriptions.</strong> Server state streams to clients via WebSocket.',

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

@@ -10,6 +10,15 @@
 //      @voltro/i18n (<T>); we mock it to resolve against the real catalog for a
 //      controllable "current locale". The hero <h1> carries a `{{capProjectName}}`
 //      scaffold placeholder, so we assert the heading EXISTS, not its text.
+//   3. the hero image renders as a <picture> with the pipeline's variants.
+//
+// WHY THE `?image` IMPORT IS MOCKED. `voltro test` runs vitest WITHOUT the
+// CLI's image plugin (it is a `voltro dev` / `voltro build` transform), so a
+// `?image` specifier resolves to a plain URL STRING under the unit runner —
+// <Image> would then fall back to the loader path and warn about the missing
+// intrinsic size. Substituting the asset OBJECT the pipeline produces keeps the
+// page code idiomatic (no hand-written width/height) and makes the <picture> /
+// blur / srcSet assertions below mean what they say.
 
 import { afterEach, describe, expect, test, vi } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
@@ -37,8 +46,27 @@ vi.mock('@voltro/i18n', () => ({
       c,
   T: ({ id, values }: { id: string; values?: Record<string, unknown> }) =>
     fill(catalogs[currentLocale]?.[id] ?? id, values),
+  // The string form, for message ids used as ATTRIBUTES (the image's `alt`).
+  useT: (id: string, values?: Record<string, unknown>): string =>
+    fill(catalogs[currentLocale]?.[id] ?? id, values),
 }))
 
+// What the `?image` pipeline hands <Image> at build time, in miniature: two
+// modern-format sources, a same-family fallback srcSet, the intrinsic size read
+// off the file, and the inlined blur placeholder.
+const HERO_ASSET = {
+  src: '/assets/hero.abc123.jpeg',
+  width: 1200,
+  height: 630,
+  blurDataURL: 'data:image/jpeg;base64,BLUR',
+  srcSet: '/assets/hero.640.jpeg 640w, /assets/hero.abc123.jpeg 1200w',
+  sources: [
+    { type: 'image/avif', srcSet: '/assets/hero.640.avif 640w, /assets/hero.1200.avif 1200w' },
+    { type: 'image/webp', srcSet: '/assets/hero.640.webp 640w, /assets/hero.1200.webp 1200w' },
+  ],
+} as const
+vi.mock('../assets/hero.jpg?image', () => ({ default: HERO_ASSET }))
+
 const { default: Index, meta, renderMode, interactive } = await import('./page')
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
@@ -108,3 +136,54 @@ describe('index — localized render', () => {
     expect(container.textContent).toContain('Bereit loszulegen?')
   })
 })
+
+describe('index — the hero image + the self-hosted font', () => {
+  test('renders a <picture> with one <source> per modern format, avif first', () => {
+    render(createElement(Index))
+    const picture = container.querySelector('picture')
+    expect(picture).toBeTruthy()
+    const types = Array.from(picture!.querySelectorAll('source')).map((s) => s.getAttribute('type'))
+    expect(types).toEqual(['image/avif', 'image/webp'])
+  })
+
+  test('the <img> carries the fallback srcSet + the intrinsic size off the asset', () => {
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    // width/height are NOT props on the page — they come off the imported
+    // asset, which is what reserves the box (CLS) without hand-written numbers.
+    expect(img.getAttribute('width')).toBe('1200')
+    expect(img.getAttribute('height')).toBe('630')
+    expect(img.getAttribute('srcset')).toBe(HERO_ASSET.srcSet)
+    expect(img.getAttribute('src')).toBe(HERO_ASSET.src)
+  })
+
+  test('priority makes it the LCP image: eager, not lazy', () => {
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    expect(img.getAttribute('loading')).toBe('eager')
+    expect(img.getAttribute('fetchpriority')).toBe('high')
+  })
+
+  test('the blur placeholder is painted behind it until it loads', () => {
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    expect(img.style.backgroundImage).toContain(HERO_ASSET.blurDataURL)
+  })
+
+  test('alt text is localized — it goes through useT, not <T>', () => {
+    currentLocale = 'de'
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    expect(img.getAttribute('alt')).toBe(de['hero.imageAlt'])
+    expect(img.getAttribute('alt')).not.toBe(en['hero.imageAlt'])
+  })
+
+  test('the hero heading references the declared family through its CSS variable', () => {
+    render(createElement(Index))
+    // `localFont('Geist')` maps the family declared in app.config.ts `fonts:`
+    // to the variable the generated shell defines. Asserting the VARIABLE (not
+    // a literal 'Geist') is the point: the slug rule stays the pipeline's.
+    const h1 = container.querySelector('main h1') as HTMLElement
+    expect(h1.style.fontFamily).toBe('var(--font-geist)')
+  })
+})

package/templates/apps/frontend-landing/src/pages/page.tsx

@@ -8,9 +8,17 @@
 // so each variant's <title> / <description> is localised in the emitted HTML.
 
 import type { ReactNode } from 'react'
-import type { PageMeta } from '@voltro/web'
-import { T } from '@voltro/i18n'
+import { Image, localFont, type PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
 import { getCatalog } from '../lib/locale'
+// The `?image` suffix opts this import into the BUILD-TIME pipeline: instead of
+// vite's plain hashed URL it resolves to an optimized-asset object — AVIF+WebP
+// variants at every ladder width up to the intrinsic 1200px plus a jpeg
+// fallback, the intrinsic width/height, and an inlined 16px blur data URI.
+// `voltro build` encodes them into dist/assets/ under content hashes (through a
+// persistent cache, so a rebuild re-encodes nothing); `voltro dev` transforms on
+// demand. Nothing here requires JS on the page — it renders as a <picture>.
+import hero from '../assets/hero.jpg?image'
 
 // Pre-render at build time. Removes the runtime dependency entirely
 // for plain-content pages — no rpc client, no react hydration. If you
@@ -32,14 +40,29 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 const strong = (chunks: ReactNode): ReactNode => <strong>{chunks}</strong>
 const code = (chunks: ReactNode): ReactNode => <code>{chunks}</code>
 
+// The typed way to name a family declared in app.config.ts `fonts:` from TSX.
+// It is a pure NAME MAPPER — `{ variable: '--font-geist', fontFamily:
+// 'var(--font-geist)' }` — so it never has to be kept in sync with the slug
+// rule by hand. src/globals.css points the kit's `--font-sans` at the same
+// variable app-wide; this is the per-component form.
+const brand = localFont('Geist')
+
 export default function Index(): ReactNode {
+  // `alt` is an ATTRIBUTE, not children, so it needs a plain string — that is
+  // what `useT` is for; `<T>` returns an element and cannot be used here.
+  const heroAlt = useT('hero.imageAlt')
   return (
     <main>
       <section>
-        <h1>{{capProjectName}}</h1>
+        <h1 style={{ fontFamily: brand.fontFamily }}>{{capProjectName}}</h1>
         <p>
           <T id="hero.tagline" />
         </p>
+        {/* `priority` marks this the LCP image: eager load + high fetch
+          * priority instead of the lazy default. width/height/blur are NOT
+          * hand-written — they come off the imported asset, which is what
+          * reserves the box and keeps CLS at zero. */}
+        <Image src={hero} alt={heroAlt} priority sizes="(max-width: 900px) 100vw, 900px" />
         <a href="#features">
           <T id="hero.cta" />
         </a>

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

@@ -1,6 +1,6 @@
 {
   "id": "frontend-landing",
   "kind": "web",
-  "summary": "Bilingual (en/de) marketing landing page: hero, features grid, CTA. Static-render mode with zero JS on the wire; URL-prefix i18n (`/` + `/de`) pre-renders one HTML file per locale. Flip interactive: 'islands' for interactive pieces.",
-  "tags": ["web", "frontend", "landing", "marketing", "static", "i18n", "intl", "localization"]
+  "summary": "Bilingual (en/de) marketing landing page: hero, features grid, CTA. Static-render mode with zero JS on the wire; URL-prefix i18n (`/` + `/de`) pre-renders one HTML file per locale. Ships the asset pipelines a marketing page actually needs: a local hero image through `?image` + `<Image>` (AVIF/WebP srcSet, inferred dimensions, blur placeholder) and a self-hosted woff2 declared under `fonts:` (hashed, size-adjusted fallback face, preload — no font CDN). Flip interactive: 'islands' for interactive pieces.",
+  "tags": ["web", "frontend", "landing", "marketing", "static", "i18n", "intl", "localization", "images", "fonts", "assets"]
 }

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-static-blog/content/posts/cms-to-ssg.md

@@ -0,0 +1,12 @@
+---
+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
+---
+
+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/content/posts/hello-static.md

@@ -0,0 +1,12 @@
+---
+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
+---
+
+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.

package/templates/apps/frontend-static-blog/content/posts/islands-not-hydration.md

@@ -0,0 +1,14 @@
+---
+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
+---
+
+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.

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

@@ -12,16 +12,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/content": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
+    "effect": "^3.22.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -0,0 +1,27 @@
+// The blog's content collection — content/posts/**/*.md through the
+// framework's content pipeline (@voltro/content). Frontmatter is
+// schema-checked at build time (a violation FAILS the build naming the file),
+// bodies render to HTML with syntax-highlighted code fences, and no markdown
+// engine ships to the browser: SSG reads the filesystem; SPA navigations
+// fetch the build-emitted JSON artifacts under /assets/content/posts/.
+//
+// Point a CMS/DB-backed site at @voltro/cms instead — files are versioned
+// DEVELOPER content, a CMS is editorial content.
+
+import { Schema } from 'effect'
+import { defineCollection } from '@voltro/content'
+
+export const posts = defineCollection({
+  name: 'posts',
+  directory: 'content/posts',
+  schema: Schema.Struct({
+    title: Schema.String,
+    /** ISO date, shown + used for ordering. */
+    date: Schema.String,
+    /** One-line summary — feeds the list + `<meta name="description">`. */
+    excerpt: Schema.String,
+    readingMinutes: Schema.Union(Schema.NumberFromString, Schema.Number),
+  }),
+})
+
+export type Post = Schema.Schema.Type<typeof posts.schema>

package/templates/apps/frontend-static-blog/src/pages/[locale]/blog/[slug]/page.tsx

@@ -7,14 +7,17 @@
 // once per non-default locale). `voltro build` produces one HTML file per
 // pair, e.g. /de/blog/hello-static.
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../../lib/locale'
-import { posts } from '../../../../content/posts'
+import { getCollection } from '@voltro/content'
+import { posts } from '../../../../collections/posts.collection'
 
 export { default } from '../../../blog/[slug]/page'
 export { renderMode, interactive, loader, meta } from '../../../blog/[slug]/page'
 
 export const getStaticPaths = async (): Promise<
   Array<{ params: { locale: string; slug: string } }>
-> =>
-  SUPPORTED_LOCALES
+> => {
+  const entries = await getCollection(posts.name)
+  return SUPPORTED_LOCALES
     .filter((l) => l !== DEFAULT_LOCALE)
-    .flatMap((locale) => posts.map((post) => ({ params: { locale, slug: post.slug } })))
+    .flatMap((locale) => entries.map((post) => ({ params: { locale, slug: post.slug } })))
+}

package/templates/apps/frontend-static-blog/src/pages/[locale]/mirrors.test.tsx

@@ -8,7 +8,13 @@
 
 import { describe, expect, test, vi } from 'vitest'
 import type { ComponentType } from 'react'
-import { posts } from '../../content/posts'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setContentRoot, getCollection } from '@voltro/content'
+import { posts as postsCollection } from '../../collections/posts.collection'
+
+setContentRoot(join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..'))
+const posts = await getCollection(postsCollection.name)
 
 // The mirrors transitively import the base pages, which import @voltro/web
 // (island / loader / notFound / useLocation via lib/locale) and @voltro/i18n.

package/templates/apps/frontend-static-blog/src/pages/blog/[slug]/page.test.tsx

@@ -10,10 +10,16 @@
 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 { posts, type Post } from '../../../content/posts'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setContentRoot, getCollection, type ContentEntry } from '@voltro/content'
+import { posts as postsCollection, type Post } from '../../../collections/posts.collection'
 import en from '../../../locales/en'
 
-const loaderData = vi.fn<() => Post>()
+// Real content: the collection reads this app's content/posts/*.md.
+setContentRoot(join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..'))
+
+const loaderData = vi.fn<() => ContentEntry<Post>>()
 
 const fill = (msg: string, values?: Record<string, unknown>): string =>
   values ? msg.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? `{${k}}`)) : msg
@@ -48,6 +54,7 @@ vi.mock('@voltro/i18n', () => ({
 }))
 
 const { default: BlogPost, getStaticPaths, loader, meta } = await import('./page')
+const posts = await getCollection<Post>(postsCollection.name)
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
 
@@ -76,6 +83,7 @@ afterEach(() => {
 describe('blog [slug] — getStaticPaths', () => {
   test('enumerates one path per post', async () => {
     const paths = await getStaticPaths()
+    expect(posts.length).toBeGreaterThan(0)
     expect(paths.map((p) => p.params.slug)).toEqual(posts.map((p) => p.slug))
   })
 })
@@ -84,7 +92,9 @@ describe('blog [slug] — loader', () => {
   test('returns the matching post for a known slug', async () => {
     const post = await loader({ params: { slug: 'hello-static' } } as never)
     expect(post.slug).toBe('hello-static')
-    expect(post.title).toContain('zero JavaScript')
+    expect(post.data.title).toContain('zero JavaScript')
+    // The loader returns RENDERED html — the component never sees markdown.
+    expect(post.html).toContain('<p>')
   })
 
   test('throws notFound for an unknown slug', async () => {
@@ -98,8 +108,8 @@ describe('blog [slug] — meta', () => {
   test('builds a per-post title + description from the loader data', () => {
     const post = posts[0]!
     const m = meta({ loaderData: post })
-    expect(m.title).toContain(post.title)
-    expect(m.description).toBe(post.excerpt)
+    expect(m.title).toContain(post.data.title)
+    expect(m.description).toBe(post.data.excerpt)
   })
 })
 
@@ -108,9 +118,9 @@ describe('blog [slug] — render', () => {
     const post = posts[1]!
     loaderData.mockReturnValue(post)
     render(createElement(BlogPost))
-    expect(container.querySelector('article h1')?.textContent).toBe(post.title)
-    expect(container.textContent).toContain(`${post.readingMinutes} min read`)
-    const paras = post.body.split('\n\n')
-    expect(container.querySelectorAll('article p').length).toBeGreaterThanOrEqual(paras.length)
+    expect(container.querySelector('article h1')?.textContent).toBe(post.data.title)
+    expect(container.textContent).toContain(`${post.data.readingMinutes} min read`)
+    // The body arrives as rendered html paragraphs.
+    expect(container.querySelectorAll('article div p').length).toBeGreaterThanOrEqual(2)
   })
 })

package/templates/apps/frontend-static-blog/src/pages/blog/[slug]/page.tsx

@@ -1,9 +1,11 @@
 // A dynamic route — `/blog/<slug>` — pre-rendered STATICALLY, one HTML
 // file per post. Three exports make that work:
 //
-//   • getStaticPaths  → enumerate which slugs to build (from the content
-//                        source; point it at a CMS/DB in a real app).
-//   • loader          → fetch THIS post's data; runs at build per slug.
+//   • getStaticPaths  → enumerate which slugs to build (from the `posts`
+//                        content collection — one .md file per post).
+//   • loader          → fetch THIS post's entry; runs at build per slug and
+//                        returns the RENDERED html (code fences highlighted
+//                        server-side; nothing markdown-shaped in the bundle).
 //   • meta(loaderData)→ per-post <title>/<description> baked into the HTML.
 //
 // `interactive: 'islands'` hydrates ONLY the <ReadingProgress> island; the
@@ -11,8 +13,9 @@
 
 import type { ReactNode } from 'react'
 import { useLoaderData, notFound, type LoaderFn, type PageMeta } from '@voltro/web'
+import { getCollection, getEntry, type ContentEntry } from '@voltro/content'
 import { T, useLocale } from '@voltro/i18n'
-import { posts, type Post } from '../../../content/posts'
+import { posts, type Post } from '../../../collections/posts.collection'
 import { withLocalePrefix } from '../../../lib/locale'
 import ReadingProgress from '../../../components/ReadingProgress.island'
 
@@ -22,14 +25,13 @@ export const interactive = 'islands' as const
 // Which concrete paths to pre-render. Every returned `params` becomes one
 // built HTML file; un-enumerated slugs are simply not built (→ 404).
 export const getStaticPaths = async (): Promise<Array<{ params: { slug: string } }>> =>
-  posts.map((post) => ({ params: { slug: post.slug } }))
+  (await getCollection(posts.name)).map((post) => ({ params: { slug: post.slug } }))
 
 // Runs at build time for each enumerated slug. Returning `notFound()` skips
-// the artifact at build / 404s at runtime — defensive, though getStaticPaths
-// only ever feeds us slugs that exist.
-export const loader: LoaderFn<Post> = async ({ params }) => {
-  const post = posts.find((p) => p.slug === params.slug)
-  if (!post) return notFound(`post ${params.slug}`)
+// the artifact at build / 404s at runtime.
+export const loader: LoaderFn<ContentEntry<Post>> = async ({ params }) => {
+  const post = await getEntry<Post>(posts.name, params.slug)
+  if (post === null) return notFound(`post ${params.slug}`)
   return post
 }
 
@@ -37,15 +39,13 @@ export const loader: LoaderFn<Post> = async ({ params }) => {
 // pre-rendered HTML (great for SEO + social cards). The title/description are
 // POST CONTENT, not chrome, so they are the same on `/blog/x` and `/de/blog/x`
 // — no per-locale variant needed here.
-export const meta = ({ loaderData }: { loaderData: Post }): PageMeta => ({
-  title: `${loaderData.title} — {{capProjectName}}`,
-  description: loaderData.excerpt,
+export const meta = ({ loaderData }: { loaderData: ContentEntry<Post> }): PageMeta => ({
+  title: `${loaderData.data.title} — {{capProjectName}}`,
+  description: loaderData.data.excerpt,
 })
 
 export default function BlogPost(): ReactNode {
-  const post = useLoaderData<Post>()
-  // The active locale (from the layout's URL provider) keeps the "all posts"
-  // link on the current language.
+  const post = useLoaderData<ContentEntry<Post>>()
   const locale = useLocale()
   return (
     <main>
@@ -56,13 +56,11 @@ export default function BlogPost(): ReactNode {
         </a>
       </p>
       <article>
-        <h1>{post.title}</h1>
+        <h1>{post.data.title}</h1>
         <p className="muted">
-          {post.date} · <T id="post.readingTimeRead" values={{ minutes: post.readingMinutes }} />
+          {post.data.date} · <T id="post.readingTimeRead" values={{ minutes: post.data.readingMinutes }} />
         </p>
-        {post.body.split('\n\n').map((para, i) => (
-          <p key={i}>{para}</p>
-        ))}
+        <div dangerouslySetInnerHTML={{ __html: post.html ?? '' }} />
       </article>
     </main>
   )