@voltro/cli 0.52.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.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/serverless": "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/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.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-dashboard/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-docs/content/docs/de/guides/first-page.md

@@ -0,0 +1,4 @@
+---
+title: Deine erste Seite
+---
+Lege eine `*.tsx`-Datei in src/pages/ ab.

package/templates/apps/frontend-docs/content/docs/de/intro/getting-started.md

@@ -0,0 +1,4 @@
+---
+title: Erste Schritte
+---
+Willkommen in der {{capProjectName}}-Dokumentation.

package/templates/apps/frontend-docs/content/docs/en/guides/first-page.md

@@ -0,0 +1,4 @@
+---
+title: Your first page
+---
+Drop a `*.tsx` file into src/pages/.

package/templates/apps/frontend-docs/content/docs/en/intro/getting-started.md

@@ -0,0 +1,4 @@
+---
+title: Getting started
+---
+Welcome to the {{capProjectName}} docs.

package/templates/apps/frontend-docs/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-docs/src/collections/docs.collection.ts

@@ -0,0 +1,21 @@
+// The docs content collection — bilingual markdown under
+// content/docs/{en,de}/**/*.md. The SLUG comes from the path below the
+// locale segment (`en/intro/getting-started.md` → `intro/getting-started`),
+// identical across locales, so the /de mirror serves the same slugs from the
+// German tree. A missing translation falls back to the default locale's
+// entry (marked `fallback: true`) instead of 404ing — incomplete
+// translations are the normal case.
+
+import { Schema } from 'effect'
+import { defineCollection } from '@voltro/content'
+
+export const docs = defineCollection({
+  name: 'docs',
+  directory: 'content/docs',
+  schema: Schema.Struct({
+    title: Schema.String,
+  }),
+  i18n: { locales: ['en', 'de'], defaultLocale: 'en', missing: 'fallback' },
+})
+
+export type Doc = Schema.Schema.Type<typeof docs.schema>

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

@@ -10,11 +10,6 @@ export default defineLocale<typeof en>()({
 
   'home.title': '{project} Dokumentation',
 
-  'docs.getting-started.title': 'Erste Schritte',
-  'docs.getting-started.body':  'Willkommen in der {{capProjectName}}-Dokumentation.',
-  'docs.first-page.title':      'Deine erste Seite',
-  'docs.first-page.body':       'Lege eine `*.tsx`-Datei in src/pages/ ab.',
-
   'docs.notFound.title': 'Nicht gefunden',
   'docs.notFound.body':  'Kein Dokument unter <code>{slug}</code>.',
 

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

@@ -14,11 +14,6 @@ export default defineCatalog({
   // `{project}` is the scaffold-substituted app name, passed as a <T> value.
   'home.title': '{project} docs',
 
-  'docs.getting-started.title': 'Getting started',
-  'docs.getting-started.body':  'Welcome to the {{capProjectName}} docs.',
-  'docs.first-page.title':      'Your first page',
-  'docs.first-page.body':       'Drop a `*.tsx` file into src/pages/.',
-
   'docs.notFound.title': 'Not found',
   'docs.notFound.body':  'No doc at <code>{slug}</code>.',
 

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

@@ -1,18 +1,26 @@
 // Locale mirror of the catch-all docs route → renders `/de/docs/<slug>`.
-// Re-exports the bare `[...slug]` page (the component + its per-locale meta
-// read locale + slug from the URL / params). This is a DYNAMIC route mirrored
-// under a DYNAMIC locale segment, so `getStaticPaths` must emit the
-// CROSS-PRODUCT of every non-default locale × every doc slug — otherwise the
-// German docs URLs are never enumerated for pre-render.
+// Re-exports the bare `[...slug]` page's component + meta; the LOADER here
+// reads the URL locale's tree of the `docs` collection (with fallback to
+// the default locale for untranslated entries). This is a DYNAMIC route
+// mirrored under a DYNAMIC locale segment, so `getStaticPaths` emits the
+// CROSS-PRODUCT of every non-default locale × every doc slug.
+import { getCollection, getEntry, type ContentEntry } from '@voltro/content'
+import { docs, type Doc } from '../../../../collections/docs.collection'
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../../lib/locale'
-import { DOCS } from '../../../docs/[...slug]/page'
 
 export { default } from '../../../docs/[...slug]/page'
 export { renderMode, interactive, meta } from '../../../docs/[...slug]/page'
 
+export const loader = async ({ params }: {
+  readonly params: { readonly slug: string; readonly locale: string }
+}): Promise<ContentEntry<Doc> | null> =>
+  await getEntry<Doc>(docs.name, params.slug, { locale: params.locale })
+
 export const getStaticPaths = async (): Promise<
   Array<{ params: { locale: string; slug: string } }>
-> =>
-  SUPPORTED_LOCALES
+> => {
+  const entries = await getCollection(docs.name)
+  return SUPPORTED_LOCALES
     .filter((l) => l !== DEFAULT_LOCALE)
-    .flatMap((locale) => DOCS.map((d) => ({ params: { locale, slug: d.slug } })))
+    .flatMap((locale) => entries.map((d) => ({ params: { locale, slug: d.slug } })))
+}

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

@@ -8,6 +8,11 @@
 // non-default locale × every doc slug.
 
 import { describe, expect, test, vi } from 'vitest'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setContentRoot } from '@voltro/content'
+
+setContentRoot(join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..'))
 
 // The mirrors transitively import the base pages, which import @voltro/i18n
 // and @voltro/web. Stub both so importing the modules doesn't require the
@@ -50,17 +55,17 @@ describe('home mirror — getStaticPaths', () => {
 describe('docs [...slug] mirror — getStaticPaths (locale × slug cross-product)', () => {
   test('emits every non-default locale paired with every doc slug', async () => {
     const paths = await slugMirror.getStaticPaths()
+    // getCollection sorts by slug.
     expect(paths).toEqual([
-      { params: { locale: 'de', slug: 'intro/getting-started' } },
       { params: { locale: 'de', slug: 'guides/first-page' } },
+      { params: { locale: 'de', slug: 'intro/getting-started' } },
     ])
   })
 
-  test('re-exports the base page component + its per-locale meta function', () => {
+  test('re-exports the base page component + its per-locale meta function', async () => {
     expect(typeof slugMirror.default).toBe('function')
-    expect(
-      slugMirror.meta({ locale: 'de', params: { slug: 'guides/first-page' } }).title,
-    ).toBe('Deine erste Seite')
+    const deDoc = await slugMirror.loader({ params: { slug: 'guides/first-page', locale: 'de' } })
+    expect(slugMirror.meta({ locale: 'de', loaderData: deDoc }).title).toBe('Deine erste Seite')
     expect(slugMirror.renderMode).toBe('static')
     expect(slugMirror.interactive).toBe('none')
   })

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

@@ -2,11 +2,19 @@
 // (the component reads its locale from the URL via the layout's provider);
 // `getStaticPaths` tells `voltro build` which locale-prefixed paths to emit.
 // The default locale is NOT listed here — it lives at the bare `/`.
+import { getCollection, type ContentEntry } from '@voltro/content'
+import { docs, type Doc } from '../../collections/docs.collection'
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
 
 export { default } from '../page'
 export { renderMode, interactive, meta } from '../page'
 
+// The URL locale selects the collection tree (German titles on /de).
+export const loader = async ({ params }: {
+  readonly params: { readonly locale: string }
+}): Promise<ReadonlyArray<ContentEntry<Doc>>> =>
+  await getCollection<Doc>(docs.name, { locale: params.locale })
+
 export const getStaticPaths = async (): Promise<Array<{ params: { locale: string } }>> =>
   SUPPORTED_LOCALES
     .filter((l) => l !== DEFAULT_LOCALE)