@voltro/cli 0.53.0 → 0.54.0

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

@@ -3,31 +3,37 @@
 // `/` — the collaborative editor, driven through `makeVoltroTestClient`
 // (`@voltro/testing/client`) rather than a hand-rolled `vi.mock('@voltro/client')`.
 //
-// WHY THE HARNESS HERE and not a mock. This page is stateful: `useCrdtText`
-// owns a sync client per document cell, seeded from the server body and
-// folding every INCOMING body back in. A `vi.mock` can return one snapshot per
-// mount, so the fold — the whole point of the page — was untestable, and the
-// suite that replaced this one never pushed a second value into a mounted
-// tree. `setSubscription` is a real server delta, so the last case below
-// asserts convergence.
+// WHY THE HARNESS HERE and not a mock. This page is stateful: `useCrdtDoc` owns
+// a sync client AND a live CRDT document per cell, seeded from the server body
+// and folding every INCOMING body back in. A `vi.mock` can return one snapshot
+// per mount, so the fold — the whole point of the page — would be untestable.
+// `setSubscription` is a real server delta, so the convergence case below is
+// the real thing.
 //
-// Two other things fall out of it: the real `@voltro/client` hooks run (so a
-// change in their loading/error semantics is caught here instead of being
-// re-implemented by the mock), and the page can be imported statically —
-// `await import('./page')` only existed to sequence around `vi.mock`'s hoist.
+// `@voltro/local-first` is NOT faked either: the real `useCrdtDoc` +
+// `useCrdtEditor` run, so what mounts is a real Tiptap editor over a real Y.Doc.
 //
-// `@voltro/local-first` is NOT faked either: the real `useCrdtText` hook
-// decodes the seeded body and turns keystrokes into encoded updates (via its
-// `crdtTextEdit` span diff), which is the behaviour worth asserting.
+// THE BOUNDARY, stated rather than hidden: these cases drive the page from the
+// SERVER side (rows arriving) and from the user's side only as far as clicking.
+// They do not type into ProseMirror — reaching the mounted editor instance from
+// outside the component would mean poking at ProseMirror internals, and a test
+// that does that asserts the editor library, not this page. The local-edit push
+// path and its echo guard are covered where they live, against the hook:
+// `useCrdtDoc.test.tsx` in `@voltro/local-first`. What IS asserted here is the
+// half a page can get wrong on its own — that a streamed body reaches the
+// editor, and that folding one produces no write back.
 
 import { afterEach, beforeEach, describe, expect, test } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
+import { Editor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import Collaboration from '@tiptap/extension-collaboration'
 import { I18nProvider } from '@voltro/i18n'
-import { crdtText, type CrdtState } from '@voltro/local-first'
+import { defaultCrdtBackend, type CrdtState } from '@voltro/local-first'
 import { makeVoltroTestClient, type VoltroTestClient } from '@voltro/testing/client'
 import enCatalog from '../locales/en'
-import IndexPage from './page'
+import IndexPage, { renderMode } from './page'
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
 
@@ -37,13 +43,29 @@ let container: HTMLDivElement
 let root: Root
 let client: VoltroTestClient
 
-/** A CRDT state holding `text`, from a fresh document. */
-const bodyWith = (text: string): CrdtState => crdtText().insert(0, text).encode()
-
-/** A REMOTE edit derived from `base`, so merging it back converges instead of
- *  interleaving two independently-created runs of the same characters. */
-const remoteEditOf = (base: CrdtState, at: number, insert: string): CrdtState =>
-  crdtText().merge(base).insert(at, insert).encode()
+/**
+ * An authoritative body holding `html`, authored the way the app authors one:
+ * through a Tiptap editor over a CRDT document. It has to be — the editor reads
+ * the document's XML fragment, so a state written by a plain text handle would
+ * decode fine and render as an EMPTY editor.
+ *
+ * `base` continues an existing document, which is what makes a second call
+ * converge with the first instead of interleaving two independent runs of the
+ * same characters.
+ */
+const bodyWith = (html: string, base?: CrdtState): CrdtState => {
+  const handle = defaultCrdtBackend.createDoc(base)
+  const editor = new Editor({
+    extensions: [
+      StarterKit.configure({ undoRedo: false }),
+      Collaboration.configure({ document: handle.raw as never }),
+    ],
+  })
+  editor.commands.setContent(html)
+  const state = handle.encodeState()
+  editor.destroy()
+  return state
+}
 
 const docRow = (over: Partial<{ id: string; title: string; body: CrdtState | null }> = {}) => ({
   id: over.id ?? 'doc_1',
@@ -69,15 +91,8 @@ const render = (): void => {
   })
 }
 
-const setTextarea = (el: HTMLTextAreaElement, value: string): void => {
-  const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')!.set!
-  act(() => {
-    setter.call(el, value)
-    el.dispatchEvent(new Event('input', { bubbles: true }))
-  })
-}
-
-const textarea = (): HTMLTextAreaElement => container.querySelector('textarea') as HTMLTextAreaElement
+/** The editor's contenteditable surface, once `useCrdtDoc` has built its doc. */
+const surface = (): HTMLElement => container.querySelector('.ProseMirror') as HTMLElement
 
 /** The harness with both writes wired. Handlers return void; the assertions
  *  read `client.calls`, which records tag + input in order. */
@@ -98,13 +113,22 @@ afterEach(() => {
   document.body.innerHTML = ''
 })
 
+describe('collab editor — the page contract', () => {
+  test('renders in the browser only — a rich-text editor cannot be prerendered', () => {
+    // Pinned because the failure is a BUILD failure with an unhelpful message:
+    // `renderMode` defaults to 'static', and Tiptap's `new Editor()` has no
+    // `window` during prerender.
+    expect(renderMode).toBe('client')
+  })
+})
+
 describe('collab editor — subscription states', () => {
   test('shows the loading hint before the first snapshot', () => {
     // A tag with NO fixture is the harness's cold state — the real thing a
     // component sees before the first delta arrives.
     render()
     expect(container.textContent).toContain('loading…')
-    expect(container.querySelector('textarea')).toBeNull()
+    expect(surface()).toBeNull()
   })
 
   test('shows the empty state + create button once a snapshot arrives with no documents', () => {
@@ -112,7 +136,7 @@ describe('collab editor — subscription states', () => {
     render()
     expect(container.textContent).toContain('No document yet')
     expect(container.querySelector('button')).not.toBeNull()
-    expect(container.querySelector('textarea')).toBeNull()
+    expect(surface()).toBeNull()
   })
 
   test('renders the error banner when the subscription errors', () => {
@@ -138,58 +162,30 @@ describe('collab editor — create', () => {
 })
 
 describe('collab editor — editing a document', () => {
-  test('binds the textarea to the decoded CRDT body', () => {
-    client = harness({ [LIST]: [docRow({ body: bodyWith('Hello') })] })
+  test('mounts an editable surface bound to the streamed CRDT body', () => {
+    client = harness({ [LIST]: [docRow({ body: bodyWith('<p>Hello</p>') })] })
     render()
-    expect(textarea()).not.toBeNull()
-    expect(textarea().value).toBe('Hello')
+    expect(surface()).not.toBeNull()
+    expect(surface().getAttribute('contenteditable')).toBe('true')
+    expect(surface().textContent).toContain('Hello')
     expect(container.textContent).toContain('Shared document')
   })
 
-  test('typing sends an encoded CRDT update via documents.setBody', () => {
-    client = harness({ [LIST]: [docRow({ body: bodyWith('Hello') })] })
-    render()
-    setTextarea(textarea(), 'Hello!')
-
-    expect(client.calls).toHaveLength(1)
-    const call = client.calls[0]!
-    expect(call.tag).toBe('documents.setBody')
-    const input = call.input as { id: string; update: unknown }
-    expect(input.id).toBe('doc_1')
-    expect(input.update).toBeInstanceOf(Uint8Array)
-  })
-
-  // The case the hand-rolled mock could not express, and the page's whole
-  // reason to exist: a body edited in ANOTHER tab arrives as a delta, and the
-  // local handle folds it in without remounting the editor.
-  test('a remote edit pushed by the server converges into the open editor', () => {
-    const base = bodyWith('Hello')
+  // The page's whole reason to exist: a body edited in ANOTHER tab arrives as a
+  // delta and folds into the OPEN editor without remounting it.
+  test('a remote edit pushed by the server converges into the open editor, and is not echoed back', () => {
+    const base = bodyWith('<p>Hello</p>')
     client = harness({ [LIST]: [docRow({ body: base })] })
     render()
-    expect(textarea().value).toBe('Hello')
+    expect(surface().textContent).toContain('Hello')
 
     act(() => {
-      client.setSubscription(LIST, [docRow({ body: remoteEditOf(base, 5, ' world') })])
+      client.setSubscription(LIST, [docRow({ body: bodyWith('<p>Hello world</p>', base) })])
     })
 
-    expect(textarea().value).toBe('Hello world')
-    // A fold is not a write — nothing is echoed back to the server.
+    expect(surface().textContent).toContain('Hello world')
+    // A fold is NOT a write. Without the hook's echo guard this is one
+    // `documents.setBody` per fold, per open tab.
     expect(client.calls).toEqual([])
   })
-
-  test('a local edit survives a concurrent remote edit — both are in the merged text', () => {
-    const base = bodyWith('Hello')
-    client = harness({ [LIST]: [docRow({ body: base })] })
-    render()
-    setTextarea(textarea(), 'Hello!')
-    expect(textarea().value).toBe('Hello!')
-
-    // The other tab branched from the SAME base and appended elsewhere.
-    act(() => {
-      client.setSubscription(LIST, [docRow({ body: remoteEditOf(base, 0, 'Oh, ') })])
-    })
-
-    expect(textarea().value).toContain('Oh, ')
-    expect(textarea().value).toContain('!')
-  })
 })

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

@@ -2,14 +2,15 @@
 // by the framework's file-convention page discovery.
 //
 // THIS is local-first collaboration over the reactive loop. The api's
-// `documents` table has a `crdtText()` `body`; this page binds ONE
-// `useCrdtText` cell (`@voltro/local-first/react`) to it:
+// `documents` table has a `crdtDoc()` `body`; this page binds ONE `useCrdtDoc`
+// cell (`@voltro/local-first/react`) to it and hands the resulting document to
+// `useCrdtEditor` (`@voltro/local-first/editor`), the Tiptap binding:
 //   1. `useSubscription('app','documents.list')` — streams the shared document
 //      (with its MERGED body) live over WebSocket; the streamed body is the
-//      hook's `remote`, folded into the local CRDT on every change,
-//   2. `useMutation('app','documents.setBody')` is the hook's `push` — every
-//      keystroke goes through `setText`, which diffs to a minimal single-span
-//      edit (the framework's `crdtTextEdit`) and queues the encoded update.
+//      hook's `remote`, folded into the local CRDT document on every change,
+//   2. `useMutation('app','documents.setBody')` is the hook's `push` — the
+//      editor's own edits surface as `onUpdate` callbacks and are queued as
+//      INCREMENTAL updates (a keystroke is bytes, not the whole document).
 //
 // The convergence is authoritative and SERVER-SIDE: the api merges each update
 // into the stored state before broadcasting, so two tabs typing at once both
@@ -17,17 +18,28 @@
 //
 // This is the app-level binding the local-first docs describe — the two names
 // nothing can derive: `push` = the setBody mutation, `remote` = the documents
-// subscription. Everything else (sync client lifecycle, offline queue, edit
-// encoding) lives in the hook.
+// subscription. Everything else (sync-client lifecycle, offline queue, retry,
+// and the ECHO GUARD that keeps a folded remote update from being pushed back)
+// lives in the hook.
 
 import { useMutation, useSubscription } from '@voltro/client'
 import { useMemo, type ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
-import { T, useTFn } from '@voltro/i18n'
-import type { CrdtState } from '@voltro/local-first'
-import { useCrdtText } from '@voltro/local-first/react'
+import { EditorContent } from '@tiptap/react'
+import { T } from '@voltro/i18n'
+import type { CrdtDocHandle, CrdtState } from '@voltro/local-first'
+import { useCrdtDoc } from '@voltro/local-first/react'
+import { useCrdtEditor } from '@voltro/local-first/editor'
 import { getCatalog } from '../locales'
 
+// A rich-text editor needs a BROWSER. `renderMode` defaults to `'static'`,
+// which pre-renders this page at build time — and Tiptap's `new Editor()` has
+// no `window` there, so the build fails outright. `'client'` renders the page
+// in the browser only, which is what a collaborative editor wants anyway: there
+// is nothing meaningful to pre-render for a document that arrives over a live
+// subscription.
+export const renderMode = 'client' as const
+
 export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
   title: getCatalog(locale)['meta.editor.title'],
 })
@@ -51,6 +63,20 @@ interface DocRow {
 const base64ToBytes = (b64: string): Uint8Array =>
   Uint8Array.from(atob(b64), (ch) => ch.charCodeAt(0))
 
+// The Tiptap surface, in its OWN component. `useCrdtDoc` builds its document in
+// an effect (never during render — that is what crashed a prerender and leaked
+// an editor under StrictMode), so `doc` is `null` on the first pass. Splitting
+// the editor out keeps `useCrdtEditor` an unconditional hook call instead of one
+// guarded by `doc !== null`.
+const RichTextSurface = ({ doc }: { readonly doc: CrdtDocHandle }): ReactNode => {
+  const editor = useCrdtEditor({ doc })
+  return (
+    <div style={{ border: '1px solid #ddd', borderRadius: 6, padding: '10px 12px', minHeight: 220, fontSize: 14 }}>
+      <EditorContent editor={editor} />
+    </div>
+  )
+}
+
 // One editor bound to ONE document. Remounted (via `key={doc.id}`) when the
 // bound document changes, so the hook's sync-client lifecycle is scoped to it.
 const DocumentEditor = ({
@@ -62,9 +88,8 @@ const DocumentEditor = ({
   readonly saving: boolean
   readonly onUpdate: (update: CrdtState) => Promise<unknown>
 }): ReactNode => {
-  const t = useTFn()
   // The authoritative state as the subscription streams it. `null` while the
-  // body is absent — useCrdtText folds nothing then, NOT an empty document.
+  // body is absent — useCrdtDoc folds nothing then, NOT an empty document.
   const remote = useMemo(
     () =>
       doc.body instanceof Uint8Array
@@ -74,7 +99,7 @@ const DocumentEditor = ({
           : null,
     [doc.body],
   )
-  const body = useCrdtText({
+  const shared = useCrdtDoc({
     cell: { table: 'documents', id: doc.id, column: 'body' },
     remote,
     // A rejected push re-drives the queued write; log it and keep the rejection.
@@ -89,15 +114,13 @@ const DocumentEditor = ({
     <section>
       <p style={{ color: '#666', fontSize: 13, margin: '0 0 8px' }}>
         <T id="editor.docLabel" values={{ title: doc.title, strong: (c: ReactNode) => <strong>{c}</strong> }} />
-        {saving ? <T id="editor.status.saving" /> : null}
+        {saving || !shared.synced ? <T id="editor.status.saving" /> : null}
       </p>
-      <textarea
-        value={body.text}
-        onChange={(event) => body.setText(event.target.value)}
-        placeholder={t('editor.placeholder')}
-        rows={12}
-        style={{ width: '100%', padding: '10px 12px', fontSize: 14, fontFamily: 'ui-monospace, monospace', resize: 'vertical', boxSizing: 'border-box' }}
-      />
+      {shared.doc !== null ? (
+        <RichTextSurface doc={shared.doc} />
+      ) : (
+        <p style={{ color: '#999', fontSize: 13 }}><T id="editor.status.loading" /></p>
+      )}
       <p style={{ color: '#999', fontSize: 12, marginTop: 8 }}><T id="editor.hint" /></p>
     </section>
   )

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

@@ -1,6 +1,6 @@
 {
   "id": "frontend-collab",
   "kind": "web",
-  "summary": "A collaborative document editor — a textarea bound to a `crdtText()` body over the reactive engine. Type in two browser tabs at once and the edits CONVERGE (server-authoritative CRDT merge), no last-write-wins loser. Pairs with api-collab: scaffold both with `create-project --api=api-collab --web=frontend-collab`.",
-  "tags": ["web", "frontend", "fullstack", "local-first", "crdt", "collaborative", "realtime", "reactive", "api-collab"]
+  "summary": "A collaborative rich-text editor — Tiptap (`useCrdtEditor`) bound to a `crdtDoc()` body through `useCrdtDoc` over the reactive engine. Type in two browser tabs at once and the edits CONVERGE (server-authoritative CRDT merge), no last-write-wins loser. Pairs with api-collab: scaffold both with `create-project --api=api-collab --web=frontend-collab`.",
+  "tags": ["web", "frontend", "fullstack", "local-first", "crdt", "collaborative", "realtime", "reactive", "rich-text", "tiptap", "api-collab"]
 }

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

@@ -15,18 +15,18 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/serverless": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/serverless": "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.53.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-dashboard/package.json

@@ -12,17 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.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.53.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-docs/package.json

@@ -12,18 +12,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/content": "0.53.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",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/web": "0.53.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.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-i18n/package.json

@@ -12,16 +12,16 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/web": "0.53.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.53.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.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/web": "0.53.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.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",