@voltro/cli 0.52.0 → 0.53.0

package/templates/apps/changelog/src/pages/page.tsx

@@ -2,16 +2,18 @@
 // locale) and mirrored at `/de` by src/pages/[locale]/index.tsx. Pure static
 // render with no client JS (`interactive: 'none'`).
 //
-// `meta` is a FUNCTION of `{ locale }` so each variant's <title>/<description>
-// is localised in the pre-rendered HTML. The release list itself is CONTENT
-// (the .mdx files) and is NOT translated — only the chrome (page meta, the
-// empty state) comes from the catalogs. Entry links are locale-prefixed via
-// `withLocalePrefix` so /de stays on /de.
+// The list comes from the `releases` CONTENT COLLECTION: the loader runs at
+// build time, decodes each entry's frontmatter against the schema, and
+// filters drafts + future-dated entries (visibleReleases). The release list
+// itself is CONTENT and is NOT translated — only the chrome comes from the
+// catalogs. Entry links are locale-prefixed via `withLocalePrefix`.
 
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
+import { useLoaderData } from '@voltro/web'
+import { getCollection } from '@voltro/content'
 import { T, useLocale } from '@voltro/i18n'
-import { releases } from '../lib/releases'
+import { releases, tagsOf, visibleReleases, type ReleaseData, type ReleaseEntry } from '../collections/releases.collection'
 import { getCatalog, withLocalePrefix } from '../lib/locale'
 
 export const renderMode = 'static' as const
@@ -25,9 +27,13 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
   }
 }
 
+export const loader = async (): Promise<ReadonlyArray<ReleaseEntry>> =>
+  visibleReleases(await getCollection<ReleaseData>(releases.name))
+
 export default function ChangelogIndex(): ReactNode {
+  const entries = useLoaderData<ReadonlyArray<ReleaseEntry>>()
   const locale = useLocale()
-  if (releases.length === 0) {
+  if (entries.length === 0) {
     return (
       <p>
         <T id="empty.body" values={{ code: (chunks: ReactNode) => <code>{chunks}</code> }} />
@@ -36,18 +42,18 @@ export default function ChangelogIndex(): ReactNode {
   }
   return (
     <div>
-      {releases.map((release) => (
+      {entries.map((release) => (
         <article key={release.slug} className="changelog-entry">
           <p className="changelog-meta">
-            <time dateTime={release.releasedAt}>{release.releasedAt}</time> · v{release.version}
-            {release.tags.map((tag) => (
+            <time dateTime={release.data.releasedAt}>{release.data.releasedAt}</time> · v{release.data.version}
+            {tagsOf(release.data).map((tag) => (
               <span key={tag} className="changelog-tag">{tag}</span>
             ))}
           </p>
           <h2>
-            <a href={withLocalePrefix(`/${release.slug}`, locale)}>{release.title}</a>
+            <a href={withLocalePrefix(`/${release.slug}`, locale)}>{release.data.title}</a>
           </h2>
-          <p>{release.summary}</p>
+          <p>{release.data.summary}</p>
         </article>
       ))}
     </div>

package/templates/apps/edge-functions/package.json

@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/serverless": "0.52.0",
+    "@voltro/cli": "0.53.0",
+    "@voltro/serverless": "0.53.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {

package/templates/apps/frontend-admin/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.53.0",
+    "@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",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.53.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,19 +12,19 @@
     "typecheck": "tsc --noEmit"
   },
   "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.53.0",
+    "@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",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
-    "@voltro/testing": "0.52.0",
+    "@voltro/devtools": "0.53.0",
+    "@voltro/testing": "0.53.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-auth/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.53.0",
+    "@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",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.53.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-blank/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.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",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.53.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,19 +12,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/cms": "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.53.0",
+    "@voltro/cli": "0.53.0",
+    "@voltro/client": "0.53.0",
+    "@voltro/cms": "0.53.0",
+    "@voltro/env": "0.53.0",
+    "@voltro/i18n": "0.53.0",
+    "@voltro/ui-shadcn": "0.53.0",
+    "@voltro/web": "0.53.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.53.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,20 +12,20 @@
     "typecheck": "tsc --noEmit"
   },
   "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/local-first": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.53.0",
+    "@voltro/cli": "0.53.0",
+    "@voltro/client": "0.53.0",
+    "@voltro/env": "0.53.0",
+    "@voltro/i18n": "0.53.0",
+    "@voltro/local-first": "0.53.0",
+    "@voltro/ui-shadcn": "0.53.0",
+    "@voltro/web": "0.53.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
-    "@voltro/testing": "0.52.0",
+    "@voltro/devtools": "0.53.0",
+    "@voltro/testing": "0.53.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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.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",
     "effect": "^3.22.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.53.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.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",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.53.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,18 @@
     "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/content": "0.53.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.52.0",
+    "@voltro/devtools": "0.53.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)

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')