@voltro/cli 0.52.0 → 0.54.0

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

@@ -1,19 +1,30 @@
 // @vitest-environment jsdom
 //
 // `/docs/[...slug]` catch-all — its `getStaticPaths` export (enumerates the
-// pre-rendered doc slugs) and the localized page render for a matched vs.
-// unknown slug. The page reads the captured slug via `useParams` (mocked to
-// drive the slug) and its per-locale prose via @voltro/i18n (mocked to resolve
-// against the real catalogs for a controllable "current locale").
+// pre-rendered doc slugs from the `docs` CONTENT COLLECTION), the loader
+// (locale-tree selection + fallback), the per-doc meta, and the page render
+// for a matched vs. unknown slug. The collection reads this app's REAL
+// content/docs/{en,de}/**/*.md files — no fixture copies to drift.
 
 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 { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setContentRoot, type ContentEntry } from '@voltro/content'
+import type { Doc } from '../../../collections/docs.collection'
 import en from '../../../locales/en'
 import de from '../../../locales/de'
 
+// The server half of the collection reads files under the app root.
+setContentRoot(join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..'))
+
 const params = vi.fn<() => Record<string, string>>()
-vi.mock('@voltro/web', () => ({ useParams: () => params() }))
+const loaderData = vi.fn<() => ContentEntry<Doc> | null>()
+vi.mock('@voltro/web', () => ({
+  useParams: () => params(),
+  useLoaderData: () => loaderData(),
+}))
 
 const catalogs: Record<string, Record<string, string>> = { en, de }
 let currentLocale = 'en'
@@ -37,7 +48,7 @@ vi.mock('@voltro/i18n', () => ({
     fill(catalogs[currentLocale]?.[id] ?? id, values),
 }))
 
-const { default: DocPage, getStaticPaths, meta, renderMode, interactive } = await import('./page')
+const { default: DocPage, getStaticPaths, loader, meta, renderMode, interactive } = await import('./page')
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
 
@@ -53,7 +64,10 @@ const render = (node: ReactNode): void => {
   })
 }
 
-beforeEach(() => params.mockReset())
+beforeEach(() => {
+  params.mockReset()
+  loaderData.mockReset()
+})
 
 afterEach(() => {
   currentLocale = 'en'
@@ -70,36 +84,59 @@ describe('docs [...slug] — config + getStaticPaths', () => {
 
   test('enumerates every doc slug as a single `/`-joined string', async () => {
     const paths = await getStaticPaths()
+    // getCollection sorts by slug.
     expect(paths.map((p) => p.params.slug)).toEqual([
-      'intro/getting-started',
       'guides/first-page',
+      'intro/getting-started',
     ])
   })
 })
 
+describe('docs [...slug] — loader (collection + locale trees)', () => {
+  test('loads the default-locale entry with rendered html', async () => {
+    const doc = await loader({ params: { slug: 'guides/first-page' } })
+    expect(doc?.data.title).toBe('Your first page')
+    expect(doc?.html).toContain('<code>*.tsx</code>')
+  })
+
+  test('loads the German tree when a locale is passed', async () => {
+    const doc = await loader({ params: { slug: 'guides/first-page' }, locale: 'de' })
+    expect(doc?.data.title).toBe('Deine erste Seite')
+    expect(doc?.html).toContain('Lege eine')
+  })
+
+  test('returns null for an unknown slug', async () => {
+    expect(await loader({ params: { slug: 'does/not-exist' } })).toBeNull()
+  })
+})
+
 describe('docs [...slug] — localized meta', () => {
-  test('reads the per-doc title from the catalog, per locale', () => {
-    expect(meta({ locale: 'en', params: { slug: 'guides/first-page' } }).title).toBe('Your first page')
-    expect(meta({ locale: 'de', params: { slug: 'guides/first-page' } }).title).toBe('Deine erste Seite')
+  test('reads the per-doc title from the entry frontmatter, per locale', async () => {
+    const enDoc = await loader({ params: { slug: 'guides/first-page' } })
+    const deDoc = await loader({ params: { slug: 'guides/first-page' }, locale: 'de' })
+    expect(meta({ locale: 'en', loaderData: enDoc }).title).toBe('Your first page')
+    expect(meta({ locale: 'de', loaderData: deDoc }).title).toBe('Deine erste Seite')
   })
 
   test('falls back to the not-found title for an unknown slug', () => {
-    expect(meta({ locale: 'en', params: { slug: 'does/not-exist' } }).title).toBe('Not found')
+    expect(meta({ locale: 'en', loaderData: null }).title).toBe('Not found')
   })
 })
 
-describe('docs [...slug] — localized render', () => {
-  test('renders the matched doc title + body (English) for a known slug', () => {
+describe('docs [...slug] — render', () => {
+  test('renders the matched doc title + body (English) for a known slug', async () => {
     currentLocale = 'en'
     params.mockReturnValue({ slug: 'guides/first-page' })
+    loaderData.mockReturnValue(await loader({ params: { slug: 'guides/first-page' } }))
     render(createElement(DocPage))
     expect(container.querySelector('h1')?.textContent).toBe('Your first page')
     expect(container.textContent).toContain('Drop a')
   })
 
-  test('renders the matched doc title + body (German) for a known slug', () => {
+  test('renders the matched doc title + body (German) for a known slug', async () => {
     currentLocale = 'de'
     params.mockReturnValue({ slug: 'guides/first-page' })
+    loaderData.mockReturnValue(await loader({ params: { slug: 'guides/first-page' }, locale: 'de' }))
     render(createElement(DocPage))
     expect(container.querySelector('h1')?.textContent).toBe('Deine erste Seite')
     expect(container.textContent).toContain('Lege eine')
@@ -108,6 +145,7 @@ describe('docs [...slug] — localized render', () => {
   test('renders the localized not-found fallback for an unknown slug', () => {
     currentLocale = 'en'
     params.mockReturnValue({ slug: 'does/not-exist' })
+    loaderData.mockReturnValue(null)
     render(createElement(DocPage))
     expect(container.querySelector('h1')?.textContent).toBe('Not found')
     expect(container.textContent).toContain('does/not-exist')

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

@@ -2,55 +2,50 @@
 // `/docs/<path>` URL (and its `/de/docs/<path>` mirror). `getStaticPaths`
 // enumerates the doc tree at build time so every page is pre-rendered.
 //
-// Bilingual (Strategy B): the doc SLUG is stable across locales — only the
-// /de URL prefix differs — so each entry carries a `titleKey` / `bodyKey`
-// into the message catalog rather than literal, one-language strings. The
-// [locale] mirror (src/pages/[locale]/docs/[...slug].tsx) re-exports this
-// page and emits the cross-product of non-default locales × these slugs.
+// Bilingual via the `docs` CONTENT COLLECTION (content/docs/{en,de}/**):
+// the SLUG is stable across locales — only the /de URL prefix and the
+// locale tree differ. This bare route reads the DEFAULT locale's tree; the
+// [locale] mirror re-exports the component and loads the requested tree
+// (with fallback to English for untranslated entries).
 
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
-import { useParams } from '@voltro/web'
-import { T, useTFn } from '@voltro/i18n'
-import { getCatalog, type Messages } from '../../../lib/locale'
+import { useLoaderData, useParams } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCollection, getEntry, type ContentEntry } from '@voltro/content'
+import { docs, type Doc } from '../../../collections/docs.collection'
+import { getCatalog } from '../../../lib/locale'
 
 export const renderMode = 'static' as const
 export const interactive = 'none' as const
 
-interface DocEntry {
-  readonly slug: string
-  readonly titleKey: keyof Messages
-  readonly bodyKey: keyof Messages
-}
-
-// The doc tree — slugs stay identical across locales; the per-locale prose
-// lives in the catalogs. Replace with a loader over a markdown folder / CMS
-// / database query; the shape stays the same.
-export const DOCS: ReadonlyArray<DocEntry> = [
-  { slug: 'intro/getting-started', titleKey: 'docs.getting-started.title', bodyKey: 'docs.getting-started.body' },
-  { slug: 'guides/first-page',     titleKey: 'docs.first-page.title',      bodyKey: 'docs.first-page.body' },
-]
-
 // getStaticPaths returns `{ params: { slug: '<path>' } }` entries — the
 // framework substitutes each into `/docs/[...slug]` to enumerate the URLs
 // to pre-render. The captured slug is the raw `/`-joined path (NOT a string
 // array) so a single deep slug like 'intro/getting-started' renders one file.
 export const getStaticPaths = async (): Promise<Array<{ params: { slug: string } }>> =>
-  DOCS.map((d) => ({ params: { slug: d.slug } }))
+  (await getCollection(docs.name)).map((d) => ({ params: { slug: d.slug } }))
+
+// Loads THIS doc's entry at build time — frontmatter decoded against the
+// collection schema, body rendered to HTML (code fences highlighted
+// server-side). The [locale] mirror passes the URL locale instead.
+export const loader = async ({ params, locale }: {
+  readonly params: { readonly slug: string }
+  readonly locale?: string
+}): Promise<ContentEntry<Doc> | null> =>
+  await getEntry<Doc>(docs.name, params.slug, locale !== undefined ? { locale } : {})
 
-// Per-locale, per-doc <title>: reads the active locale + the captured slug
-// (both threaded in at SSG time) so each variant's head is localised.
+// Per-locale, per-doc <title> from the entry's frontmatter.
 export const meta = ({
   locale,
-  params,
+  loaderData,
 }: {
   locale: string
-  params: Readonly<Record<string, string>>
+  loaderData: ContentEntry<Doc> | null
 }): PageMeta => {
   const c = getCatalog(locale)
-  const doc = DOCS.find((d) => d.slug === params.slug)
   return {
-    title: doc ? c[doc.titleKey] : c['docs.notFound.title'],
+    title: loaderData?.data.title ?? c['docs.notFound.title'],
     description: c['meta.docs.description'],
   }
 }
@@ -59,8 +54,7 @@ const code = (chunks: ReactNode): ReactNode => <code>{chunks}</code>
 
 export default function DocPage(): ReactNode {
   const { slug } = useParams<{ slug: string }>()
-  const t = useTFn()
-  const doc = DOCS.find((d) => d.slug === slug)
+  const doc = useLoaderData<ContentEntry<Doc> | null>()
   if (!doc) {
     return (
       <article>
@@ -75,8 +69,8 @@ export default function DocPage(): ReactNode {
   }
   return (
     <article>
-      <h1>{t(doc.titleKey)}</h1>
-      <p>{t(doc.bodyKey)}</p>
+      <h1>{doc.data.title}</h1>
+      <div dangerouslySetInnerHTML={{ __html: doc.html ?? '' }} />
     </article>
   )
 }

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

@@ -10,15 +10,25 @@
 import { afterEach, describe, expect, test, vi } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setContentRoot } from '@voltro/content'
 import en from '../locales/en'
 import de from '../locales/de'
 
+// The link list comes from the docs CONTENT COLLECTION — real files.
+setContentRoot(join(dirname(fileURLToPath(import.meta.url)), '..', '..'))
+
 const catalogs: Record<string, Record<string, string>> = { en, de }
 let currentLocale = 'en'
 
 const fill = (msg: string, values?: Record<string, unknown>): string =>
   values ? msg.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? `{${k}}`)) : msg
 
+vi.mock('@voltro/web', () => ({
+  useLoaderData: () => entriesByLocale[currentLocale] ?? entriesByLocale['en'],
+}))
+
 vi.mock('@voltro/i18n', () => ({
   // The locale catalogs call these at module top-level; identity mirrors the
   // real (compile-time-only) implementations so importing them doesn't throw.
@@ -32,7 +42,11 @@ vi.mock('@voltro/i18n', () => ({
     fill(catalogs[currentLocale]?.[id] ?? id, values),
 }))
 
-const { default: Index, meta, renderMode, interactive } = await import('./page')
+const { default: Index, meta, renderMode, interactive, loader } = await import('./page')
+const entriesByLocale: Record<string, Awaited<ReturnType<typeof loader>>> = {
+  en: await loader(),
+  de: await loader({ locale: 'de' }),
+}
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
 
@@ -75,7 +89,7 @@ describe('index — localized render', () => {
   test('links to both doc pages with bare (en) URLs and English titles', () => {
     currentLocale = 'en'
     render(createElement(Index))
-    expect(hrefs()).toEqual(['/docs/intro/getting-started', '/docs/guides/first-page'])
+    expect(hrefs()).toEqual(['/docs/guides/first-page', '/docs/intro/getting-started'])
     expect(container.textContent).toContain('Getting started')
     expect(container.textContent).toContain('Your first page')
   })
@@ -83,7 +97,7 @@ describe('index — localized render', () => {
   test('prefixes the doc links with /de and shows German titles for locale de', () => {
     currentLocale = 'de'
     render(createElement(Index))
-    expect(hrefs()).toEqual(['/de/docs/intro/getting-started', '/de/docs/guides/first-page'])
+    expect(hrefs()).toEqual(['/de/docs/guides/first-page', '/de/docs/intro/getting-started'])
     expect(container.textContent).toContain('Erste Schritte')
     expect(container.textContent).toContain('Deine erste Seite')
   })

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

@@ -2,12 +2,17 @@
 // themselves live under `src/pages/docs/[...slug].tsx`.
 //
 // Bilingual (Strategy B): mounted at `/` (default locale) and mirrored at
-// `/de` by src/pages/[locale]/index.tsx. The links are locale-prefixed off
-// the active locale so /de's landing points at the /de docs.
+// `/de` by src/pages/[locale]/index.tsx. The link list comes from the `docs`
+// CONTENT COLLECTION — titles are the entries' frontmatter, per locale tree
+// (the /de mirror passes its locale into the loader), so a new .md file
+// appears here without touching this page.
 
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
+import { useLoaderData } from '@voltro/web'
+import { getCollection, type ContentEntry } from '@voltro/content'
 import { T, useLocale } from '@voltro/i18n'
+import { docs, type Doc } from '../collections/docs.collection'
 import { getCatalog, withLocalePrefix } from '../lib/locale'
 
 export const renderMode = 'static' as const
@@ -21,7 +26,11 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
   }
 }
 
+export const loader = async ({ locale }: { readonly locale?: string } = {}): Promise<ReadonlyArray<ContentEntry<Doc>>> =>
+  await getCollection<Doc>(docs.name, locale !== undefined ? { locale } : {})
+
 export default function Index(): ReactNode {
+  const entries = useLoaderData<ReadonlyArray<ContentEntry<Doc>>>()
   const locale = useLocale()
   return (
     <main>
@@ -29,16 +38,11 @@ export default function Index(): ReactNode {
         <T id="home.title" values={{ project: '{{capProjectName}}' }} />
       </h1>
       <ul>
-        <li>
-          <a href={withLocalePrefix('/docs/intro/getting-started', locale)}>
-            <T id="docs.getting-started.title" />
-          </a>
-        </li>
-        <li>
-          <a href={withLocalePrefix('/docs/guides/first-page', locale)}>
-            <T id="docs.first-page.title" />
-          </a>
-        </li>
+        {entries.map((doc) => (
+          <li key={doc.slug}>
+            <a href={withLocalePrefix(`/docs/${doc.slug}`, locale)}>{doc.data.title}</a>
+          </li>
+        ))}
       </ul>
     </main>
   )

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

@@ -12,16 +12,16 @@
     "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/env": "0.54.0",
+    "@voltro/i18n": "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-landing/README.md

@@ -15,3 +15,51 @@ pnpm --filter @{{projectName}}/{{appName}} dev
 When you need a contact form / sign-up flow, switch
 `interactive: 'islands'` on the page and mark the interactive
 component with the `*.island.tsx` suffix so only that bundle ships.
+
+## The hero image — `?image` + `<Image>`
+
+`src/assets/hero.jpg` is imported with the **`?image` suffix**, which is the
+explicit opt-in to the build-time pipeline: the import resolves to an optimized
+**asset object** instead of vite's plain hashed URL, and `<Image src={hero}>`
+renders it as a `<picture>` with one `<source>` per modern format.
+
+- **`voltro build`** encodes AVIF + WebP + a jpeg fallback at every ladder width
+  up to the intrinsic 1200px into `dist/assets/` under content hashes, through a
+  persistent cache (`.framework/image-cache/`) — a rebuild re-encodes nothing.
+- **`voltro dev`** transforms on demand from `/_voltro/image/<assetId>`.
+- **`voltro start`** serves build artifacts only; there is deliberately no
+  production transform endpoint.
+
+`width`, `height` and the blur placeholder are **not props** — they are read off
+the asset, which is what reserves the box (CLS ≈ 0) without hand-written
+numbers. `priority` marks it the LCP image (eager + high fetch priority).
+
+Encoding runs on [sharp](https://sharp.pixelplumbing.com), an optional
+dependency of `@voltro/cli` — nothing to install. If your installer omits
+optional dependencies the pipeline serves the original with one loud warning
+naming the fix; `voltro doctor` tells "not installed" from "binary missing".
+
+A **dynamic** `src` (a URL from a loader or CMS frontmatter) cannot be seen at
+build time — use the loader seam instead: `<Image src={url} loader={cdn} />`.
+
+## The font — self-hosted, no CDN
+
+`app.config.ts` declares one family under `fonts:`, pointing at the woff2
+committed in `src/fonts/`. The build content-hashes it and serves it from **your
+origin**, emits `@font-face`, computes a **size-adjusted fallback face** from the
+file's real metrics so the swap moves no text, and puts a `<link rel="preload">`
+in the one shell every render mode serves. `subsets: ['latin']` ships only the
+range the page's characters need.
+
+Nothing talks to Google Fonts (or any font host) at runtime — the visitor's IP
+never reaches a font CDN, because no request leaves your domain.
+
+Reference the family from CSS via the `--font-geist` variable the shell defines
+(`src/globals.css` points the kit's `--font-sans` at it), or from TSX via
+`localFont('Geist')` — a pure name mapper, so the slug rule stays the
+pipeline's.
+
+**Swapping in your own face:** drop the `woff2` **and its licence file** into
+`src/fonts/`, then change `family` + `path` in `app.config.ts`. The framework
+ships no font downloader on purpose — licence terms differ per family. The
+bundled Geist is SIL OFL 1.1 (see `src/fonts/LICENSE-Geist.txt`).

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

@@ -21,5 +21,33 @@ export default {
   // drives the [locale] mirror routing + the language switcher.
   locales:       ['en', 'de'] as const,
   defaultLocale: 'en'         as const,
+  // Self-hosted local font. The file is committed next to this config
+  // (src/fonts/) WITH its licence — Geist is SIL OFL 1.1 (Vercel /
+  // basement.studio), see src/fonts/LICENSE-Geist.txt. The framework ships no
+  // font DOWNLOADER on purpose (licence terms differ per family), so swapping
+  // in your own brand face is: drop the woff2 + its licence here, change
+  // `family` + `path`.
+  //
+  // What `voltro build` / `voltro dev` do with this: content-hash the file and
+  // serve it from YOUR origin (no font-CDN request ever leaves the browser —
+  // the GDPR answer), emit `@font-face` with `font-display`, compute a
+  // SIZE-ADJUSTED `'Geist Fallback'` face from the file's real metrics so the
+  // swap moves no text (CLS ≈ 0), and put a `<link rel="preload">` in the one
+  // generated shell every render mode serves.
+  //
+  // ONE variable face covers the whole 100–900 range, so the page makes a
+  // single font request. `subsets: ['latin']` (U+0000–00FF) covers both
+  // shipped locales — German umlauts and ß live inside that range.
+  //
+  // src/globals.css points the kit's `--font-sans` at the `--font-geist`
+  // variable the shell defines; src/pages/page.tsx reads the same variable
+  // from TSX via `localFont('Geist')`.
+  fonts: [{
+    family: 'Geist',
+    src: [{ path: 'src/fonts/Geist-Variable.woff2', weight: '100 900' }],
+    display: 'swap' as const,
+    subsets: ['latin'] as ReadonlyArray<'latin' | 'latin-ext'>,
+    fallback: 'Arial' as const,
+  }],
   env,
 }

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

@@ -12,16 +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/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-landing/src/fonts/LICENSE-Geist.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2023 Vercel, in collaboration with basement.studio
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/templates/apps/frontend-landing/src/globals.css

@@ -11,8 +11,23 @@
  * vite-plugin auto-detect stops firing. */
 @source "./**/*.{tsx,ts,jsx,js}";
 
+/* Point the kit's `--font-sans` at the family the framework's font pipeline
+ * self-hosts. `--font-geist` is defined by the generated shell (the
+ * `<style data-voltro-fonts>` block) from the `fonts:` declaration in
+ * app.config.ts, and expands to `'Geist', 'Geist Fallback', Arial,
+ * sans-serif` — the second entry being the size-adjusted metric fallback the
+ * pipeline computes, which is what keeps the swap from moving any text.
+ *
+ * Without this line the declaration would still self-host the file, but no
+ * rule would reference the family: the page would ship a font it never uses. */
+:root {
+  --font-sans: var(--font-geist);
+}
+
 html, body { min-height: 100vh; }
 
+body { font-family: var(--font-sans); }
+
 /* Gradient title — use on hero <h1> via `className="gradient-title"`. */
 .gradient-title {
   background: linear-gradient(180deg, var(--foreground) 0%, oklch(0.7 0.18 290) 100%);

package/templates/apps/frontend-landing/src/globals.d.ts

@@ -4,3 +4,20 @@
 // 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'
+
+// `declare module '*?image'`: the build-time image pipeline. The `?image`
+// suffix on an image import is an explicit opt-in — it turns the import into
+// this optimized-asset OBJECT (srcSet variants + intrinsic size + a blur data
+// URI) instead of vite's plain hashed-URL string, so a bare image import keeps
+// its usual semantics. `<Image src={asset}>` consumes exactly this shape.
+declare module '*?image' {
+  const asset: {
+    readonly src: string
+    readonly width: number
+    readonly height: number
+    readonly blurDataURL: string
+    readonly srcSet: string
+    readonly sources: ReadonlyArray<{ readonly type: string; readonly srcSet: string }>
+  }
+  export default asset
+}

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

@@ -8,8 +8,9 @@ export default defineLocale<typeof en>()({
   'nav.home':     'Start',
   'nav.language': 'Sprache',
 
-  'hero.tagline': 'Ersetze diesen Hero-Text durch dein Nutzenversprechen.',
-  'hero.cta':     'Mehr erfahren →',
+  'hero.tagline':  'Ersetze diesen Hero-Text durch dein Nutzenversprechen.',
+  'hero.cta':      'Mehr erfahren →',
+  'hero.imageAlt': 'Abstrakte Verlaufsgrafik',
 
   'features.heading':     'Funktionen',
   'features.reactive':    '<strong>Reaktive Subscriptions.</strong> Server-Status streamt per WebSocket zu den Clients.',