@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/frontend-portal/src/pages/(portal)/api-keys/page.tsx

@@ -0,0 +1,124 @@
+// API keys — URL `/api-keys`. Drives the framework's BUILT-IN key management
+// surface (`GET/POST /v1/api-keys*`), which the api exposes when it sets
+// `apiKeys: true`. Keys are hash-stored; the raw token is shown exactly ONCE at
+// mint time and is unrecoverable after.
+//
+// This surface is admin-scoped and off by default, so the page DEGRADES: a 404
+// means the api hasn't enabled `apiKeys`, a 401/403 means the signed-in user
+// lacks the scope. It tells the operator exactly what to turn on rather than
+// showing a broken table. (api-saas-starter does not enable it out of the box —
+// see the README.)
+import type { ReactNode } from 'react'
+import { useEffect, useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import type { ApiKey } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.apiKeys.title'],
+})
+
+type State = 'loading' | 'ready' | 'notEnabled' | 'noAccess' | 'error'
+
+const BASE = '/v1/api-keys'
+
+export default function ApiKeys(): ReactNode {
+  const [state, setState] = useState<State>('loading')
+  const [keys, setKeys] = useState<ReadonlyArray<ApiKey>>([])
+  const [name, setName] = useState('')
+  const [minted, setMinted] = useState<string | null>(null)
+  const [pending, setPending] = useState(false)
+  const nameLabel = useT('apiKeys.name.placeholder')
+
+  const load = (): void => {
+    void fetch(BASE, { headers: { accept: 'application/json' } })
+      .then(async (res) => {
+        if (res.ok) {
+          const body = (await res.json()) as { keys: ReadonlyArray<ApiKey> }
+          setKeys(body.keys ?? [])
+          setState('ready')
+        } else if (res.status === 404) setState('notEnabled')
+        else if (res.status === 401 || res.status === 403) setState('noAccess')
+        else setState('error')
+      })
+      .catch(() => setState('error'))
+  }
+
+  useEffect(load, [])
+
+  const onIssue = (e: FormEvent): void => {
+    e.preventDefault()
+    const trimmed = name.trim()
+    if (trimmed === '') return
+    setPending(true)
+    setMinted(null)
+    void fetch(`${BASE}/issue`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: trimmed }),
+    })
+      .then(async (res) => {
+        if (res.ok) {
+          const body = (await res.json()) as { token: string }
+          setMinted(body.token)
+          setName('')
+          load()
+        }
+      })
+      .finally(() => setPending(false))
+  }
+
+  const onRevoke = (id: string): void => {
+    void fetch(`${BASE}/revoke`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id }),
+    }).then(() => load())
+  }
+
+  return (
+    <section>
+      <h1><T id="apiKeys.heading" /></h1>
+
+      {state === 'loading' ? <p className="empty"><T id="apiKeys.loading" /></p> : null}
+      {state === 'notEnabled' ? <p className="notice" role="status"><T id="apiKeys.notEnabled" /></p> : null}
+      {state === 'noAccess' ? <p className="notice" role="status"><T id="apiKeys.noAccess" /></p> : null}
+      {state === 'error' ? <p className="error-text" role="alert"><T id="apiKeys.error" /></p> : null}
+
+      {state === 'ready' ? (
+        <>
+          <form className="row" onSubmit={onIssue} style={{ marginTop: '0.5rem' }}>
+            <input aria-label={nameLabel} placeholder={nameLabel} value={name} onChange={(e) => setName(e.target.value)} />
+            <button type="submit" className="btn" disabled={pending}><T id="apiKeys.issue" /></button>
+          </form>
+
+          {minted ? (
+            <div className="paywall" role="alert" style={{ marginTop: '1rem' }}>
+              <strong><T id="apiKeys.minted.title" /></strong>
+              <p className="muted"><T id="apiKeys.minted.body" /></p>
+              <code className="token">{minted}</code>
+            </div>
+          ) : null}
+
+          {keys.length === 0 ? (
+            <p className="empty"><T id="apiKeys.empty" /></p>
+          ) : (
+            <ul className="rows" style={{ marginTop: '1.25rem' }}>
+              {keys.map((k) => (
+                <li key={k.id}>
+                  <span className="grow">{k.name} <code>{k.keyPrefix}…</code></span>
+                  {k.revokedAt
+                    ? <span className="tag"><T id="apiKeys.revoked" /></span>
+                    : <button type="button" className="link" onClick={() => onRevoke(k.id)}><T id="apiKeys.revoke" /></button>}
+                </li>
+              ))}
+            </ul>
+          )}
+        </>
+      ) : null}
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/billing/page.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+//
+// The billing page. We mock `@voltro/client` (the live subscription + the three
+// billing actions) and assert: the current plan renders, and the plan-change
+// flow quotes the provider's proration BEFORE it can be confirmed (preview →
+// confirm), not a locally-estimated figure.
+
+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 subData = vi.fn<() => { data: unknown }>()
+const previewRun = vi.fn<(input: unknown) => Promise<unknown>>()
+
+vi.mock('@voltro/client', () => ({
+  useSubscription: () => subData(),
+  useAction: (_api: string, tag: string) => ({
+    run: tag === 'billing.previewChange' ? previewRun : vi.fn().mockResolvedValue({ url: 'https://provider/portal' }),
+    pending: false,
+  }),
+}))
+
+const { default: Billing, meta, renderMode } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+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(() => {
+  subData.mockReset()
+  subData.mockReturnValue({ data: { subscription: { plan: 'free', status: 'active', quantity: 1, currentPeriodEnd: null, cancelAt: null } } })
+  previewRun.mockReset()
+  previewRun.mockResolvedValue({ plan: 'pro', quantity: 1, prorationMinor: 900, currency: 'usd' })
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('billing — config', () => {
+  test('is an SSR page titled Billing (so the parent gate runs per request)', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Billing')
+  })
+})
+
+describe('billing — render + change flow', () => {
+  test('shows the current plan', () => {
+    render(createElement(Billing))
+    expect(container.textContent).toContain('free')
+    expect(container.textContent).toContain('Current plan')
+  })
+
+  test('previewing the upgrade quotes the provider proration before confirm appears', async () => {
+    render(createElement(Billing))
+    // Before preview: the button is "Preview upgrade", not "Confirm".
+    expect(container.textContent).toContain('Preview upgrade')
+    expect(container.textContent).not.toContain('Confirm upgrade')
+
+    const previewBtn = Array.from(container.querySelectorAll('button')).find((b) => b.textContent === 'Preview upgrade')!
+    await act(async () => {
+      previewBtn.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+      await Promise.resolve(); await Promise.resolve()
+    })
+    expect(previewRun).toHaveBeenCalledWith({ plan: 'pro' })
+    // The quote is shown and now the confirm button is available.
+    expect(container.textContent).toContain('settles at about')
+    expect(container.textContent).toContain('Confirm upgrade')
+  })
+})

package/templates/apps/frontend-portal/src/pages/(portal)/billing/page.tsx

@@ -0,0 +1,97 @@
+// Billing — URL `/billing`. The current plan (live from `billing.subscription`),
+// a card-management button that redirects to the PROVIDER's hosted portal
+// (`billing.portalUrl`), and a plan change that QUOTES the provider's prorated
+// settlement first (`billing.previewChange`) before applying it
+// (`billing.changePlan`) — never a locally-estimated figure.
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useSubscription, useAction } from '@voltro/client'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import { formatMoney, type ChangePreview, type SubscriptionState } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.billing.title'],
+})
+
+// The plan a free tenant upgrades to — matches api-saas-starter's `plans`.
+const UPGRADE_PLAN = 'pro'
+
+export default function Billing(): ReactNode {
+  const locale = useLocale()
+  const { data } = useSubscription<SubscriptionState>('app', 'billing.subscription')
+  const portal = useAction<{ returnUrl: string }, { url: string }>('app', 'billing.portalUrl')
+  const preview = useAction<{ plan?: string; quantity?: number }, ChangePreview>('app', 'billing.previewChange')
+  const change = useAction<{ plan: string }, ChangePreview>('app', 'billing.changePlan')
+
+  const [quote, setQuote] = useState<ChangePreview | null>(null)
+  const [changed, setChanged] = useState(false)
+  const sub = data?.subscription ?? null
+  const freeLabel = useT('billing.plan.free')
+  const busy = portal.pending || preview.pending || change.pending
+
+  const onManageCard = (): void => {
+    const here = typeof window === 'undefined' ? '/billing' : window.location.href
+    void portal.run({ returnUrl: here })
+      .then((r) => { if (r && typeof window !== 'undefined') window.location.assign(r.url) })
+      .catch(() => { /* surfaced via portal.error */ })
+  }
+
+  const onPreview = (): void => {
+    setChanged(false)
+    void preview.run({ plan: UPGRADE_PLAN }).then((q) => setQuote(q)).catch(() => setQuote(null))
+  }
+
+  const onConfirm = (): void => {
+    void change.run({ plan: UPGRADE_PLAN }).then(() => { setChanged(true); setQuote(null) }).catch(() => { /* change.error */ })
+  }
+
+  return (
+    <section>
+      <h1><T id="billing.heading" /></h1>
+
+      <dl className="facts">
+        <dt><T id="billing.plan.label" /></dt>
+        <dd>{sub?.plan ?? freeLabel}</dd>
+        <dt><T id="billing.status.label" /></dt>
+        <dd>{sub?.status ?? '—'}</dd>
+        <dt><T id="billing.seats.label" /></dt>
+        <dd>{sub?.quantity ?? 1}</dd>
+      </dl>
+
+      <div className="row" style={{ marginTop: '1.25rem' }}>
+        <button type="button" className="btn ghost" disabled={busy} onClick={onManageCard}>
+          <T id="billing.card.manage" />
+        </button>
+      </div>
+
+      <div className="paywall" style={{ marginTop: '1.5rem' }}>
+        <strong><T id="billing.change.title" /></strong>
+        <p className="muted"><T id="billing.change.body" /></p>
+        {quote ? (
+          <p role="status">
+            <T
+              id="billing.change.quote"
+              values={{ amount: formatMoney(Math.abs(quote.prorationMinor), quote.currency, locale) }}
+            />
+          </p>
+        ) : null}
+        {changed ? <p className="ok" role="status"><T id="billing.change.done" /></p> : null}
+        <div className="row">
+          {quote ? (
+            <button type="button" className="btn" disabled={busy} onClick={onConfirm}>
+              <T id={change.pending ? 'billing.pending' : 'billing.change.confirm'} />
+            </button>
+          ) : (
+            <button type="button" className="btn" disabled={busy} onClick={onPreview}>
+              <T id={preview.pending ? 'billing.pending' : 'billing.change.preview'} />
+            </button>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/error.tsx

@@ -0,0 +1,19 @@
+// Error boundary scoped to the portal subtree. A render error (or a loader
+// rejection that ISN'T a RedirectError / NotFoundError) bubbles here.
+import type { ReactNode } from 'react'
+import type { ErrorBoundaryProps } from '@voltro/web'
+import { T } from '@voltro/i18n'
+
+export default function PortalError({ error, reset }: ErrorBoundaryProps): ReactNode {
+  return (
+    <div className="dash">
+      <main>
+        <h1><T id="error.heading" /></h1>
+        <p className="muted">{String(error)}</p>
+        <p style={{ marginTop: '1rem' }}>
+          <button type="button" className="btn" onClick={reset}><T id="error.retry" /></button>
+        </p>
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/invoices/page.tsx

@@ -0,0 +1,45 @@
+// Invoices — URL `/invoices`. Lists the tenant's invoice history live from
+// `billing.invoices`. Each row's amount/status is shown; "View" / "PDF" link OUT
+// to the provider's own hosted pages (`hostedUrl` / `pdfUrl`) — the portal never
+// renders an invoice document itself.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+import { T, useLocale } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import { formatMoney, type Invoice } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.invoices.title'],
+})
+
+export default function Invoices(): ReactNode {
+  const locale = useLocale()
+  const { data } = useSubscription<{ invoices: ReadonlyArray<Invoice> }>('app', 'billing.invoices')
+  const invoices = data?.invoices ?? []
+
+  return (
+    <section>
+      <h1><T id="invoices.heading" /></h1>
+      {invoices.length === 0 ? (
+        <p className="empty"><T id="invoices.empty" /></p>
+      ) : (
+        <ul className="rows" style={{ marginTop: '1.25rem' }}>
+          {invoices.map((inv) => (
+            <li key={inv.providerInvoiceId}>
+              <span className="grow">
+                {inv.createdAt ? new Date(inv.createdAt).toLocaleDateString() : '—'}
+              </span>
+              <span>{formatMoney(inv.amountMinor, inv.currency, locale)}</span>
+              <span className="tag">{inv.status}</span>
+              {inv.hostedUrl ? <a href={inv.hostedUrl} target="_blank" rel="noopener noreferrer"><T id="invoices.view" /></a> : null}
+              {inv.pdfUrl ? <a href={inv.pdfUrl} target="_blank" rel="noopener noreferrer"><T id="invoices.pdf" /></a> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/layout.test.tsx

@@ -0,0 +1,31 @@
+// The portal auth GATE, tested at the loader. Server-side (a `query` fn is
+// present) it asks the api's `session.me`: an anonymous identity must throw
+// RedirectError to /login; a `user` identity resolves with the tenant. On a
+// client navigation (`query` undefined) it resolves permissively.
+
+import { describe, expect, test, vi } from 'vitest'
+import { RedirectError } from '@voltro/web'
+import { loader } from './layout'
+import type { Identity } from '../../lib/api'
+
+const queryReturning = (identity: Identity) =>
+  vi.fn(async (_tag: string, _input: unknown) => identity as unknown)
+
+describe('portal gate — loader', () => {
+  test('redirects an anonymous caller to /login', async () => {
+    const query = queryReturning({ type: 'anonymous', id: null, tenantId: null })
+    await expect(loader({ query } as never)).rejects.toBeInstanceOf(RedirectError)
+    expect(query).toHaveBeenCalledWith('session.me', {})
+  })
+
+  test('lets a signed-in user through and returns the tenant', async () => {
+    const query = queryReturning({ type: 'user', id: 'u_1', tenantId: 'acme' })
+    const data = await loader({ query } as never)
+    expect(data).toEqual({ tenantId: 'acme' })
+  })
+
+  test('client navigation (no server query fn) resolves without re-gating', async () => {
+    const data = await loader({ query: undefined } as never)
+    expect(data).toEqual({ tenantId: null })
+  })
+})

package/templates/apps/frontend-portal/src/pages/(portal)/layout.tsx

@@ -0,0 +1,63 @@
+// The portal shell — and the AUTH GATE. This layout wraps every page in the
+// silent `(portal)` group, and its `loader` runs server-side BEFORE the pages
+// render: it asks the api's `session.me` and throws RedirectError to /login for
+// anyone not signed in. The pages under here are `renderMode: 'ssr'` precisely so
+// this runs per request.
+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 type { Identity } from '../../lib/api'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+interface PortalData {
+  readonly tenantId: string | null
+}
+
+export const loader: LoaderFn<PortalData> = async ({ query }) => {
+  if (query) {
+    const me = await query<Identity>('session.me', {})
+    if (me.type !== 'user') {
+      throw new RedirectError('/login?from=/')
+    }
+    return { tenantId: me.tenantId }
+  }
+  return { tenantId: null }
+}
+
+export default function PortalLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  useLoaderData<PortalData>()
+  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('/', <T id="nav.overview" />)}
+          {navItem('/billing', <T id="nav.billing" />)}
+          {navItem('/invoices', <T id="nav.invoices" />)}
+          {navItem('/api-keys', <T id="nav.apiKeys" />)}
+          {navItem('/profile', <T id="nav.profile" />)}
+        </nav>
+      </aside>
+      <main>
+        <div className="topbar">
+          <span className="spacer" />
+          <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+        </div>
+        {children}
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/not-found.tsx

@@ -0,0 +1,15 @@
+// Scoped 404 for the portal subtree.
+import type { ReactNode } from 'react'
+import { T } from '@voltro/i18n'
+
+export default function PortalNotFound(): 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="/"><T id="notFound.back" /></a></p>
+      </main>
+    </div>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/page.tsx

@@ -0,0 +1,39 @@
+// Overview — URL `/`. A glance at the account: the current plan (live from
+// `billing.subscription`), renewal date, and quick links into the deeper pages.
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+import type { SubscriptionState } from '../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.overview.title'],
+})
+
+export default function Overview(): ReactNode {
+  const { data } = useSubscription<SubscriptionState>('app', 'billing.subscription')
+  const sub = data?.subscription ?? null
+  const freeLabel = useT('billing.plan.free')
+
+  return (
+    <section>
+      <h1><T id="overview.heading" /></h1>
+      <dl className="facts">
+        <dt><T id="billing.plan.label" /></dt>
+        <dd>{sub?.plan ?? freeLabel}</dd>
+        <dt><T id="billing.status.label" /></dt>
+        <dd>{sub?.status ?? '—'}</dd>
+        <dt><T id="overview.renews" /></dt>
+        <dd>{sub?.currentPeriodEnd ? new Date(sub.currentPeriodEnd).toLocaleDateString() : '—'}</dd>
+      </dl>
+      <ul className="cards" style={{ marginTop: '1.5rem' }}>
+        <li className="card"><a href="/billing"><T id="nav.billing" /></a><div className="label"><T id="overview.link.billing" /></div></li>
+        <li className="card"><a href="/invoices"><T id="nav.invoices" /></a><div className="label"><T id="overview.link.invoices" /></div></li>
+        <li className="card"><a href="/api-keys"><T id="nav.apiKeys" /></a><div className="label"><T id="overview.link.apiKeys" /></div></li>
+      </ul>
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/profile/page.tsx

@@ -0,0 +1,79 @@
+// Profile — URL `/profile`. Shows the signed-in identity (from the gate's
+// `session.me`, re-read here), a self-contained password-change (requests a reset
+// link via the api's `/auth/password-reset` route), and sign out. Kept
+// deliberately thin — the portal is account admin, not a settings sprawl.
+import type { ReactNode } from 'react'
+import { useEffect, useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useAction } from '@voltro/client'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import type { Identity } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.profile.title'],
+})
+
+const csrf = async (): Promise<string> => {
+  const body = (await fetch('/auth/csrf').then((r) => r.json())) as { csrfToken?: string }
+  return body.csrfToken ?? ''
+}
+
+export default function Profile(): ReactNode {
+  const me = useAction<Record<string, never>, Identity>('app', 'session.me')
+  const [ident, setIdent] = useState<Identity | null>(null)
+  const [email, setEmail] = useState('')
+  const [sent, setSent] = useState(false)
+  const emailLabel = useT('profile.cp.email')
+
+  useEffect(() => {
+    void me.run({}).then(setIdent).catch(() => setIdent(null))
+  }, []) // read the identity once on mount
+
+  const onChangePassword = (e: FormEvent): void => {
+    e.preventDefault()
+    void csrf()
+      .then((token) =>
+        fetch('/auth/password-reset', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'x-csrf-token': token },
+          body: JSON.stringify({ email }),
+        }),
+      )
+      .finally(() => setSent(true))
+  }
+
+  const signOut = (): void => {
+    void csrf()
+      .then((token) => fetch('/auth/sign-out', { method: 'POST', headers: { 'x-csrf-token': token } }))
+      .finally(() => window.location.assign('/login'))
+  }
+
+  return (
+    <section>
+      <h1><T id="profile.heading" /></h1>
+      <dl className="facts">
+        <dt><T id="profile.id" /></dt>
+        <dd><code>{ident?.id ?? '—'}</code></dd>
+        <dt><T id="profile.tenant" /></dt>
+        <dd><code>{ident?.tenantId ?? '—'}</code></dd>
+      </dl>
+
+      <h2 style={{ marginTop: '1.5rem' }}><T id="profile.cp.heading" /></h2>
+      {sent ? (
+        <p className="ok" role="status"><T id="profile.cp.sent" /></p>
+      ) : (
+        <form className="row" onSubmit={onChangePassword}>
+          <input type="email" required aria-label={emailLabel} placeholder={emailLabel} value={email} onChange={(e) => setEmail(e.target.value)} />
+          <button type="submit" className="btn ghost"><T id="profile.cp.submit" /></button>
+        </form>
+      )}
+
+      <div className="row" style={{ marginTop: '1.5rem' }}>
+        <button type="button" className="btn" onClick={signOut}><T id="profile.signOut" /></button>
+      </div>
+    </section>
+  )
+}

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

@@ -0,0 +1,12 @@
+// Root layout — wraps EVERY page (marketing + dashboard). 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}</>
+}