@voltro/cli 0.1.0

package/templates/apps/frontend-dashboard/src/pages/dashboard/index.tsx

@@ -0,0 +1,38 @@
+// Dashboard overview — URL `/dashboard`. `renderMode: 'ssr'` so the parent
+// layout's auth-gate loader runs per request (see dashboard/layout.tsx).
+// A real app would read live data with `useSubscription` from an api here;
+// this template keeps it backend-free, so the figures are placeholders.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.overview.title'],
+})
+
+const stats = [
+  { labelId: 'overview.stat.projects', value: '12' },
+  { labelId: 'overview.stat.members', value: '37' },
+  { labelId: 'overview.stat.issues', value: '4' },
+  { labelId: 'overview.stat.uptime', value: '99.9%' },
+] as const
+
+export default function Overview(): ReactNode {
+  return (
+    <section>
+      <h1><T id="overview.heading" /></h1>
+      <p className="muted"><T id="overview.intro" /></p>
+      <div className="cards" style={{ marginTop: '1.25rem' }}>
+        {stats.map((s) => (
+          <div className="card" key={s.labelId}>
+            <div className="label"><T id={s.labelId} /></div>
+            <div className="value">{s.value}</div>
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/dashboard/layout.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+//
+// The dashboard shell + AUTH GATE. The loader redirects an unauthenticated
+// request (throws RedirectError) and otherwise returns the shared user data the
+// layout renders. We mock the framework hooks (useLoaderData / useLocation) so
+// the render is standalone, and import the REAL RedirectError so the loader's
+// throw is observable.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { RedirectError } from '@voltro/web'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../locales/en'
+
+const loaderData = vi.fn<() => unknown>()
+const location = vi.fn<() => string>()
+
+vi.mock('@voltro/web', async () => {
+  const actual = await vi.importActual<typeof import('@voltro/web')>('@voltro/web')
+  return { ...actual, useLoaderData: () => loaderData(), useLocation: () => location() }
+})
+
+const { default: DashboardLayout, loader } = await import('./layout')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// DashboardLayout uses <T>/useLocale + <LocaleSwitcher>, so wrap renders in the
+// framework's <I18nProvider> (auto-wired in the running app).
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+afterEach(() => {
+  loaderData.mockReset()
+  location.mockReset()
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('dashboard layout — loader (auth gate)', () => {
+  test('redirects to /login (remembering the destination) when no session cookie is present', async () => {
+    const err = await Promise.resolve(loader({ headers: {} } as never)).catch((e: unknown) => e)
+    expect(err).toBeInstanceOf(RedirectError)
+    expect((err as RedirectError).location).toBe('/login?from=/dashboard')
+  })
+
+  test('returns the shared user for a signed-in request', async () => {
+    const data = await loader({ headers: { cookie: 'demo_session=ok' } } as never)
+    expect(data.user.name).toBe('Demo User')
+    expect(data.user.plan).toBe('Pro')
+  })
+})
+
+describe('dashboard layout — render', () => {
+  test('renders the user, plan, and nav links', () => {
+    loaderData.mockReturnValue({ user: { name: 'Ada', plan: 'Enterprise' } })
+    location.mockReturnValue('/dashboard')
+    render(createElement(DashboardLayout, { children: createElement('p', null, 'page body') }))
+    expect(container.textContent).toContain('Ada')
+    expect(container.textContent).toContain('Enterprise plan')
+    const hrefs = Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+    expect(hrefs).toContain('/dashboard')
+    expect(hrefs).toContain('/dashboard/settings')
+    expect(container.querySelector('main')!.textContent).toContain('page body')
+  })
+
+  test('marks the active nav link with aria-current for the current path', () => {
+    loaderData.mockReturnValue({ user: { name: 'Ada', plan: 'Pro' } })
+    location.mockReturnValue('/dashboard/settings')
+    render(createElement(DashboardLayout, { children: null }))
+    const active = Array.from(container.querySelectorAll('a')).find(
+      (a) => a.getAttribute('aria-current') === 'page',
+    )!
+    expect(active.getAttribute('href')).toBe('/dashboard/settings')
+  })
+})

package/templates/apps/frontend-dashboard/src/pages/dashboard/layout.tsx

@@ -0,0 +1,69 @@
+// The dashboard shell — and the AUTH GATE. This nested layout wraps every
+// page under `/dashboard`, and its `loader` runs ONCE for all of them,
+// server-side, BEFORE the page renders. That makes it the right seam to
+// validate the session + preload shared data in one place.
+//
+// Throwing RedirectError short-circuits the whole subtree: on SSR it emits a
+// 303 + Location; on a client navigation it `navigate(.., { replace:true })`
+// so Back doesn't bounce onto the redirecting page. The pages under here are
+// `renderMode: 'ssr'` precisely so this runs per request — a `static` page
+// can't redirect per-visitor, and the build rejects a RedirectError there.
+import type { ReactNode } from 'react'
+import { RedirectError, useLoaderData, useLocation, type LoaderFn } from '@voltro/web'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../../config'
+import { isSignedIn } from '../../lib/auth'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+interface DashboardData {
+  readonly user: { readonly name: string; readonly plan: string }
+}
+
+export const loader: LoaderFn<DashboardData> = async ({ headers }) => {
+  if (!isSignedIn(headers)) {
+    // No session → bounce to login, remembering where they were headed.
+    throw new RedirectError('/login?from=/dashboard')
+  }
+  // Shared data, loaded once for every page beneath this layout and read
+  // via useLoaderData<DashboardData>() right here in the layout.
+  return { user: { name: 'Demo User', plan: 'Pro' } }
+}
+
+export default function DashboardLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  const { user } = useLoaderData<DashboardData>()
+  const pathname = useLocation()
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  const navItem = (href: string, label: ReactNode): ReactNode => (
+    <a href={href} aria-current={pathname === href ? 'page' : undefined}>
+      {label}
+    </a>
+  )
+
+  return (
+    <div className="dash">
+      <aside>
+        <div className="brand">{APP_NAME}</div>
+        <nav>
+          {navItem('/dashboard', <T id="dash.nav.overview" />)}
+          {navItem('/dashboard/settings', <T id="dash.nav.settings" />)}
+          <a href="/"><T id="dash.nav.backToSite" /></a>
+        </nav>
+      </aside>
+      <main>
+        <div className="topbar">
+          <strong>{user.name}</strong>
+          <span className="muted"><T id="dash.planSuffix" values={{ plan: user.plan }} /></span>
+          <span className="spacer" />
+          <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+        </div>
+        {children}
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/dashboard/loading.tsx

@@ -0,0 +1,21 @@
+// OPT-IN loading skeleton for /dashboard pages. By default navigation is
+// deferred (the previous page stays until the loader settles — no overlay).
+// Adding `loading.tsx` opts THIS subtree into swapping in immediately and
+// showing a skeleton instead, which suits a data-backed dashboard where the
+// loader may take a beat.
+import type { ReactNode } from 'react'
+
+export default function DashboardLoading(): ReactNode {
+  return (
+    <div className="dash">
+      <main>
+        <div className="cards" aria-hidden="true">
+          <div className="skeleton" />
+          <div className="skeleton" />
+          <div className="skeleton" />
+          <div className="skeleton" />
+        </div>
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/dashboard/not-found.tsx

@@ -0,0 +1,19 @@
+// Scoped 404 for the /dashboard subtree. Fires when a URL is under
+// `/dashboard/...` but no concrete page matches (e.g. /dashboard/nope), and
+// when a loader throws NotFoundError. The router picks the deepest matching
+// not-found scope, so this handles dashboard misses while the rest of the
+// app falls back to the router default.
+import type { ReactNode } from 'react'
+import { T } from '@voltro/i18n'
+
+export default function DashboardNotFound(): ReactNode {
+  return (
+    <div className="dash">
+      <main>
+        <h1><T id="notFound.heading" /></h1>
+        <p className="muted"><T id="notFound.body" /></p>
+        <p style={{ marginTop: '1rem' }}><a href="/dashboard"><T id="notFound.back" /></a></p>
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/dashboard/settings.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+//
+// `/dashboard/settings` — SSR page whose only behaviour is a "sign out" button
+// that clears the demo cookie + hard-navigates to `/`. We assert the config
+// exports and that clicking Sign out expires the SESSION_COOKIE.
+
+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 { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../locales/en'
+
+const { default: Settings, meta, renderMode } = await import('./settings')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// The page uses <T>, so wrap renders in the framework's <I18nProvider>.
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+beforeEach(() => {
+  // Seed a session cookie so we can observe it being cleared.
+  document.cookie = 'demo_session=ok; path=/'
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+describe('settings — config', () => {
+  test('is an SSR page titled Settings', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Settings')
+  })
+})
+
+describe('settings — sign out', () => {
+  test('expires the session cookie and hard-navigates home', () => {
+    // jsdom's location.assign is a non-configurable no-op that throws "not
+    // implemented"; replace the whole location object so we can observe the
+    // hard-navigation target.
+    const assign = vi.fn()
+    vi.stubGlobal('location', { ...window.location, assign, href: '' })
+
+    render(createElement(Settings))
+    const btn = Array.from(container.querySelectorAll('button')).find(
+      (b) => (b.textContent ?? '').includes('Sign out'),
+    )!
+    act(() => { btn.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+
+    expect(document.cookie).not.toContain('demo_session=ok')
+    expect(assign).toHaveBeenCalledWith('/')
+  })
+})

package/templates/apps/frontend-dashboard/src/pages/dashboard/settings.tsx

@@ -0,0 +1,35 @@
+// Settings — URL `/dashboard/settings`. Also `renderMode: 'ssr'`, so it's
+// gated by the same parent layout loader. The "sign out" button clears the
+// demo cookie and hard-navigates to `/` so the next visit to /dashboard
+// hits the gate fresh and is redirected to /login.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+import { SESSION_COOKIE } from '../../lib/auth'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.settings.title'],
+})
+
+export default function Settings(): ReactNode {
+  const signOut = (): void => {
+    // Expire the cookie, then hard-navigate so the gate re-evaluates.
+    document.cookie = `${SESSION_COOKIE}=; path=/; max-age=0`
+    window.location.assign('/')
+  }
+
+  return (
+    <section>
+      <h1><T id="settings.heading" /></h1>
+      <p className="muted"><T id="settings.intro" /></p>
+      <p style={{ marginTop: '1.5rem' }}>
+        <button type="button" className="btn" onClick={signOut}>
+          <T id="settings.signOut" />
+        </button>
+      </p>
+    </section>
+  )
+}

package/templates/apps/frontend-dashboard/src/pages/layout.tsx

@@ -0,0 +1,12 @@
+// Root layout — wraps EVERY page (marketing + dashboard). It's intentionally
+// thin: it loads the stylesheet and lets each AREA layout
+// ((marketing)/layout.tsx, dashboard/layout.tsx) supply its own chrome.
+// Layouts nest, so a dashboard page is wrapped root → dashboard.
+//
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+import type { ReactNode } from 'react'
+import '../globals.css'
+
+export default function RootLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  return <>{children}</>
+}

package/templates/apps/frontend-dashboard/src/pages/layouts.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+//
+// Render smokes for the root layout (passes children through) and the
+// (marketing) group layout (brand header + nav links wrapping the children).
+
+import { afterEach, describe, expect, test } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../locales/en'
+
+const { default: RootLayout } = await import('./layout')
+const { default: MarketingLayout } = await import('./(marketing)/layout')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+// MarketingLayout uses <T>/useLocale + <LocaleSwitcher>, so wrap renders in the
+// framework's <I18nProvider> (auto-wired in the running app).
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('root layout', () => {
+  test('renders its children unchanged', () => {
+    render(createElement(RootLayout, { children: createElement('p', null, 'hello') }))
+    expect(container.textContent).toContain('hello')
+  })
+})
+
+describe('marketing layout', () => {
+  test('renders the header nav (Dashboard + Sign in) around the children', () => {
+    render(createElement(MarketingLayout, { children: createElement('p', null, 'body') }))
+    const hrefs = Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+    expect(hrefs).toContain('/dashboard')
+    expect(hrefs).toContain('/login')
+    expect(container.textContent).toContain('body')
+  })
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-dashboard",
+  "kind": "web",
+  "summary": "An authenticated dashboard shell — a silent (marketing) route group for public pages, a /dashboard area gated by a nested layout loader that RedirectErrors to /login when there's no session, and scoped error/loading/not-found special files. SSR auth gate, no backend.",
+  "tags": ["web", "frontend", "dashboard", "auth", "route-groups", "ssr", "layouts"]
+}

package/templates/apps/frontend-dashboard/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", ".framework"]
+}

package/templates/apps/frontend-docs/README.md

@@ -0,0 +1,19 @@
+# {{projectName}} / {{appName}}
+
+Documentation site (template: **frontend-docs**).
+
+`src/pages/docs/[...slug].tsx` is the catch-all doc renderer.
+`getStaticPaths` enumerates every doc URL at build time and
+`voltro build` pre-renders them all — the result is a static site
+you can deploy anywhere.
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:5173
+# → http://localhost:5173/docs/intro/getting-started
+```
+
+The starter ships a tiny in-file `DOCS` array. Replace it with a
+real loader (markdown reader, CMS query, database fetch) — the
+component contract stays the same.

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

@@ -0,0 +1,25 @@
+// `port` is allocated by `voltro create-project` / `voltro add-app` from
+// the project's portRange (in project.json).
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed PUBLIC environment — public vars are validated + baked into the browser
+// bundle at build time and read via `publicEnv` from '@voltro/env/public'
+// (typed, autocompleted). NEVER put a secret here (it would ship to every
+// visitor) — declare secrets on the api instead. Run `voltro env` for the manifest.
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  // The shipped catalogs (Strategy B: URL-prefix i18n). `defaultLocale`
+  // lives at the bare path (`/docs/…`); every other locale is prefixed
+  // (`/de/docs/…`). `voltro build` pre-renders one HTML file per locale ×
+  // doc. Keep this in sync with SUPPORTED_LOCALES / DEFAULT_LOCALE in
+  // src/lib/locale.ts — that file drives the [locale] mirror routing.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  env,
+}

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

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@voltro/cli": "0.1.0",
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/i18n": "0.1.0",
+    "@voltro/ui-shadcn": "0.1.0",
+    "@voltro/web": "0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

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

@@ -0,0 +1,32 @@
+/* Docs template — design tokens + Tailwind. `@voltro/ui-shadcn/tokens.css`
+ * pulls Tailwind + the shadcn palette + the @theme mapping. */
+
+@import "@voltro/ui-shadcn/tokens.css";
+
+/* Scan THIS app's source so utility classes used only here (not in
+ * the kit) get generated. The kit declares its own @source for its
+ * files; once an explicit @source is in play, Tailwind v4's vite
+ * auto-detect doesn't fire — every consumer needs to declare its
+ * own scan target. */
+@source "./**/*.{tsx,ts,jsx,js}";
+
+html, body { min-height: 100vh; }
+
+/* Prose typography for rendered markdown. The DocShell composition
+ * already applies Tailwind's `prose prose-invert` to the <main>;
+ * this block tunes specifics for the docs catalogue. */
+.docs-prose h1 { font-size: 2rem; font-weight: 700; letter-spacing: -0.02em; margin: 0 0 1rem; color: var(--foreground); }
+.docs-prose h2 { font-size: 1.4rem; font-weight: 600; margin: 2rem 0 0.75rem; color: var(--foreground); }
+.docs-prose h3 { font-size: 1.1rem; font-weight: 600; margin: 1.5rem 0 0.5rem; color: var(--foreground); }
+.docs-prose p  { margin: 0.5rem 0; line-height: 1.6; color: var(--muted-foreground); }
+.docs-prose a  { color: var(--primary); text-decoration: underline; }
+.docs-prose code { background: var(--muted); padding: 2px 4px; border-radius: 3px; font-size: 0.85em; }
+.docs-prose pre { background: oklch(0.18 0.005 280); padding: 1rem; border-radius: 6px; overflow-x: auto; margin: 1rem 0; }
+.docs-prose pre code { background: transparent; padding: 0; }
+.docs-prose ul { margin: 0.5rem 0; padding-left: 1.5rem; }
+.docs-prose li { margin: 0.25rem 0; color: var(--muted-foreground); }
+
+.docs-prose h2 .anchor,
+.docs-prose h3 .anchor { opacity: 0; margin-right: 0.5rem; color: var(--muted-foreground); text-decoration: none; }
+.docs-prose h2:hover .anchor,
+.docs-prose h3:hover .anchor { opacity: 1; }

package/templates/apps/frontend-docs/src/lib/locale.test.ts

@@ -0,0 +1,72 @@
+// The URL-prefix i18n helpers — the load-bearing pure functions that drive the
+// [locale] mirror routing + the language switcher. `useUrlLocale` (the one hook
+// in this module) reads useLocation from @voltro/web; the rest are pure string
+// functions we can exercise directly.
+
+import { describe, expect, test } from 'vitest'
+import {
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE,
+  getCatalog,
+  localeFromPathname,
+  withLocalePrefix,
+  stripLocalePrefix,
+} from './locale'
+
+describe('locale constants', () => {
+  test('supports en + de with en as the default', () => {
+    expect(SUPPORTED_LOCALES).toEqual(['en', 'de'])
+    expect(DEFAULT_LOCALE).toBe('en')
+  })
+})
+
+describe('getCatalog', () => {
+  test('returns the matching catalog for a supported locale', () => {
+    expect(getCatalog('de')['nav.home']).toBe('Start')
+    expect(getCatalog('en')['nav.home']).toBe('Home')
+  })
+
+  test('falls back to the default catalog for an unsupported locale', () => {
+    expect(getCatalog('zz')['nav.home']).toBe('Home')
+  })
+})
+
+describe('localeFromPathname', () => {
+  test('extracts a prefixed locale', () => {
+    expect(localeFromPathname('/de')).toBe('de')
+    expect(localeFromPathname('/de/docs/intro/getting-started')).toBe('de')
+  })
+
+  test('defaults to en for the bare path or an unknown prefix', () => {
+    expect(localeFromPathname('/')).toBe('en')
+    expect(localeFromPathname('/docs/intro/getting-started')).toBe('en')
+    expect(localeFromPathname('/fr/docs/x')).toBe('en')
+  })
+})
+
+describe('withLocalePrefix', () => {
+  test('leaves default-locale paths bare', () => {
+    expect(withLocalePrefix('/docs/x', 'en')).toBe('/docs/x')
+    expect(withLocalePrefix('/', 'en')).toBe('/')
+  })
+
+  test('prefixes non-default locales, mapping / to /<locale>', () => {
+    expect(withLocalePrefix('/docs/x', 'de')).toBe('/de/docs/x')
+    expect(withLocalePrefix('/', 'de')).toBe('/de')
+  })
+})
+
+describe('stripLocalePrefix', () => {
+  test('removes a locale prefix, mapping /<locale> back to /', () => {
+    expect(stripLocalePrefix('/de/docs/x')).toBe('/docs/x')
+    expect(stripLocalePrefix('/de')).toBe('/')
+  })
+
+  test('leaves an unprefixed path unchanged', () => {
+    expect(stripLocalePrefix('/docs/x')).toBe('/docs/x')
+  })
+
+  test('round-trips with withLocalePrefix', () => {
+    expect(stripLocalePrefix(withLocalePrefix('/docs/x', 'de'))).toBe('/docs/x')
+  })
+})