@voltro/cli 0.28.0 → 0.30.0

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

@@ -0,0 +1,41 @@
+// German catalog. Mirrors every key in `en.ts` — `defineLocale<typeof en>()`
+// fails the build on a missing/misspelled key. Translate prose only; keep ICU
+// placeholders (`{days}`, `{percent}`, `{when}`) identical to en.ts.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.title':       'Status',
+  'meta.description': 'Live-Servicestatus, Verfügbarkeit und Störungsverlauf.',
+
+  'lang.label':   'Sprache',
+  'header.status': 'Status',
+
+  'overall.operational':  'Alle Systeme betriebsbereit',
+  'overall.degraded':     'Einige Systeme beeinträchtigt',
+  'overall.major_outage': 'Schwerwiegende Störung',
+
+  'uptime.heading': 'Verfügbarkeit über {days} Tage',
+  'uptime.percent': '{percent}% Verfügbarkeit',
+
+  'components.heading':          'Komponenten',
+  'components.empty':            'Noch keine Komponenten konfiguriert.',
+  'comp.status.operational':     'Betriebsbereit',
+  'comp.status.degraded':        'Beeinträchtigt',
+  'comp.status.partial_outage':  'Teilausfall',
+  'comp.status.major_outage':    'Schwerer Ausfall',
+
+  'incidents.heading':  'Störungen',
+  'incidents.none':     'Keine Störungen gemeldet.',
+  'incident.started':   'Begonnen {when}',
+  'incident.ongoing':   'Andauernd',
+  'incident.resolved':  'Behoben {when}',
+
+  'impact.minor':          'Gering',
+  'impact.major':          'Erheblich',
+  'impact.critical':       'Kritisch',
+  'status.investigating':  'Wird untersucht',
+  'status.identified':     'Identifiziert',
+  'status.monitoring':     'Wird beobachtet',
+  'status.resolved':       'Behoben',
+})

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

@@ -0,0 +1,45 @@
+// Base catalog — source of truth. Every key MUST be mirrored in `de.ts`
+// (`defineLocale<typeof en>()` enforces parity at build time). ICU `{token}`
+// placeholders are substituted via `<T values={{ … }} />`.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'meta.title':       'Status',
+  'meta.description': 'Live service status, uptime and incident history.',
+
+  'lang.label':   'Language',
+  'header.status': 'Status',
+
+  // Overall banner
+  'overall.operational':  'All systems operational',
+  'overall.degraded':     'Some systems degraded',
+  'overall.major_outage': 'Major outage',
+
+  // Uptime
+  'uptime.heading': '{days}-day uptime',
+  'uptime.percent': '{percent}% uptime',
+
+  // Components
+  'components.heading':          'Components',
+  'components.empty':            'No components configured yet.',
+  'comp.status.operational':     'Operational',
+  'comp.status.degraded':        'Degraded',
+  'comp.status.partial_outage':  'Partial outage',
+  'comp.status.major_outage':    'Major outage',
+
+  // Incidents
+  'incidents.heading':  'Incidents',
+  'incidents.none':     'No incidents reported.',
+  'incident.started':   'Started {when}',
+  'incident.ongoing':   'Ongoing',
+  'incident.resolved':  'Resolved {when}',
+
+  // Impact + lifecycle labels
+  'impact.minor':          'Minor',
+  'impact.major':          'Major',
+  'impact.critical':       'Critical',
+  'status.investigating':  'Investigating',
+  'status.identified':     'Identified',
+  'status.monitoring':     'Monitoring',
+  'status.resolved':       'Resolved',
+} as const)

package/templates/apps/frontend-status/src/locales/index.ts

@@ -0,0 +1,13 @@
+// Catalog lookup OUTSIDE React — for the page's `meta({ locale })` locale-aware
+// <title>. Cookie-i18n (no URL prefix), so @voltro/web hands `meta` the active
+// locale from the `voltro:locale` cookie. Inside React use `<T>` / `useT()`.
+import en from './en'
+import de from './de'
+
+// Both catalogs share `en`'s keys (defineLocale enforces the mirror), so a
+// known-key lookup returns `string` — what `PageMeta.title` requires under
+// exactOptionalPropertyTypes.
+export type Messages = Record<keyof typeof en, string>
+
+export const getCatalog = (locale?: string): Messages =>
+  (locale === 'de' ? de : en) as Messages

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

@@ -0,0 +1,27 @@
+// Root layout — the status-page header (brand + language) and the stylesheet.
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+import type { ReactNode } from 'react'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../config'
+import '../globals.css'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  return (
+    <div className="shell">
+      <header>
+        <span className="brand">{APP_NAME} <span className="muted"><T id="header.status" /></span></span>
+        <span className="spacer" />
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+      </header>
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+//
+// The status page. We mock `@voltro/web` (the loader hook) + `@voltro/client`
+// (the three subscriptions, keyed by tag) and assert: the loader drains the api,
+// the SSR snapshot renders the banner/components/incidents, live subscription
+// data overrides the snapshot, and the pure status math (banner + uptime) is
+// correct on its own.
+
+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'
+import { deriveOverall, uptimeGrid, uptimePercent, type Incident } from '../lib/status'
+
+const loaderData = vi.fn<() => unknown>()
+const subs = new Map<string, unknown>()
+vi.mock('@voltro/web', () => ({ useLoaderData: () => loaderData() }))
+vi.mock('@voltro/client', () => ({ useSubscription: (_api: string, tag: string) => ({ data: subs.get(tag) }) }))
+
+const { default: StatusPage, meta, loader, 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 }),
+    )
+  })
+}
+
+const emptyData = { incidents: [], components: [], updates: [] }
+
+beforeEach(() => {
+  loaderData.mockReset()
+  loaderData.mockReturnValue(emptyData)
+  subs.clear()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('status page — config + loader', () => {
+  test('is an SSR page titled Status', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Status')
+  })
+
+  test('the loader drains all three feeds from the api', async () => {
+    const query = vi.fn(async (tag: string) =>
+      tag === 'incidents.live'  ? [{ id: 'inc_1' }]
+      : tag === 'components.list' ? [{ id: 'cmp_1' }]
+      : [{ id: 'iu_1' }])
+    const data = await loader({ query } as never)
+    expect(query).toHaveBeenCalledWith('incidents.live', {})
+    expect(data.incidents).toHaveLength(1)
+    expect(data.components).toHaveLength(1)
+    expect(data.updates).toHaveLength(1)
+  })
+
+  test('returns empty feeds on a client navigation (no server query fn)', async () => {
+    const data = await loader({ query: undefined } as never)
+    expect(data).toEqual(emptyData)
+  })
+})
+
+describe('status page — render', () => {
+  test('shows the all-operational banner with no incidents', () => {
+    render(createElement(StatusPage))
+    expect(container.querySelector('.banner--operational')).not.toBeNull()
+    expect(container.textContent).toContain('All systems operational')
+  })
+
+  test('renders a live incident over the (empty) SSR snapshot', () => {
+    subs.set('incidents.live', [
+      { id: 'inc_9', title: 'API degraded', impact: 'major', status: 'investigating', startedAt: '2026-08-01T00:00:00Z', resolvedAt: null },
+    ])
+    subs.set('updates.list', [
+      { id: 'iu_1', incidentId: 'inc_9', body: 'Looking into it', status: 'investigating', createdAt: '2026-08-01T00:05:00Z' },
+    ])
+    render(createElement(StatusPage))
+    expect(container.querySelector('.banner--degraded')).not.toBeNull()
+    expect(container.textContent).toContain('API degraded')
+    expect(container.querySelector('.timeline')).not.toBeNull()
+    expect(container.textContent).toContain('Looking into it')
+  })
+})
+
+describe('status math (pure)', () => {
+  const inc = (over: Partial<Incident>): Incident => ({
+    id: 'i', title: 't', impact: 'minor', status: 'investigating',
+    startedAt: '2026-08-01T00:00:00Z', resolvedAt: null, ...over,
+  })
+
+  test('deriveOverall escalates with impact and clears when resolved', () => {
+    expect(deriveOverall([], [])).toBe('operational')
+    expect(deriveOverall([inc({ impact: 'major' })], [])).toBe('degraded')
+    expect(deriveOverall([inc({ impact: 'critical' })], [])).toBe('major_outage')
+    expect(deriveOverall([inc({ impact: 'critical', status: 'resolved', resolvedAt: '2026-08-02T00:00:00Z' })], [])).toBe('operational')
+    expect(deriveOverall([], [{ id: 'c', name: 'API', status: 'major_outage' }])).toBe('major_outage')
+  })
+
+  test('uptimeGrid marks a day down only for a major/critical incident overlapping it', () => {
+    const now = Date.parse('2026-08-10T12:00:00Z')
+    const minorOnly = uptimeGrid([inc({ impact: 'minor', startedAt: '2026-08-09T00:00:00Z', resolvedAt: '2026-08-09T06:00:00Z' })], now, 90)
+    expect(minorOnly.every(Boolean)).toBe(true)          // minor never dings uptime
+    expect(uptimePercent(minorOnly)).toBe(100)
+
+    const majorDay = uptimeGrid([inc({ impact: 'critical', startedAt: '2026-08-09T00:00:00Z', resolvedAt: '2026-08-09T06:00:00Z' })], now, 90)
+    expect(majorDay.filter((up) => !up)).toHaveLength(1)  // exactly one down day
+    expect(uptimePercent(majorDay)).toBeLessThan(100)
+  })
+})

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

@@ -0,0 +1,136 @@
+// `/` — the public status page. `renderMode: 'ssr'`, fed by the sibling api:
+// the loader bakes the current incidents + components + updates into the first
+// paint (crawlable), then the component upgrades each to live with
+// `useSubscription`, so a newly-declared or resolved incident lands on every
+// open page within seconds — no polling.
+import type { ReactNode } from 'react'
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../locales'
+import {
+  deriveOverall, uptimeGrid, uptimePercent,
+  type Incident, type Component, type Update,
+} from '../lib/status'
+
+interface PageData {
+  readonly incidents: ReadonlyArray<Incident>
+  readonly components: ReadonlyArray<Component>
+  readonly updates: ReadonlyArray<Update>
+}
+
+export const renderMode = 'ssr' as const
+
+// `query` is present ONLY server-side. It invokes the api's rpc over POST /rpc;
+// a streaming query is drained to its first snapshot. On a client navigation
+// `query` is undefined and we start empty — the subscriptions fill in.
+export const loader: LoaderFn<PageData> = async ({ query }) => ({
+  incidents:  query ? await query<ReadonlyArray<Incident>>('incidents.live', {}) : [],
+  components: query ? await query<ReadonlyArray<Component>>('components.list', {}) : [],
+  updates:    query ? await query<ReadonlyArray<Update>>('updates.list', {}) : [],
+})
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title:       getCatalog(locale)['meta.title'],
+  description: getCatalog(locale)['meta.description'],
+})
+
+const fmtDate = (v: string | Date | null): string =>
+  v == null ? '' : new Date(v).toLocaleString()
+
+export default function StatusPage(): ReactNode {
+  const initial = useLoaderData<PageData>()
+  const { data: iLive } = useSubscription<ReadonlyArray<Incident>>('app', 'incidents.live')
+  const { data: cLive } = useSubscription<ReadonlyArray<Component>>('app', 'components.list')
+  const { data: uLive } = useSubscription<ReadonlyArray<Update>>('app', 'updates.list')
+
+  const incidents  = iLive ?? initial.incidents
+  const components = cLive ?? initial.components
+  const updates    = uLive ?? initial.updates
+
+  const overall = deriveOverall(incidents, components)
+  const grid = uptimeGrid(incidents)
+  const pct = uptimePercent(grid)
+
+  const updatesFor = (incidentId: string): ReadonlyArray<Update> =>
+    updates
+      .filter((u) => u.incidentId === incidentId)
+      .slice()
+      .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime())
+
+  return (
+    <main>
+      {/* Overall banner */}
+      <div className={`banner banner--${overall}`} role="status">
+        <span className="dot" aria-hidden="true" />
+        <strong><T id={`overall.${overall}`} /></strong>
+      </div>
+
+      {/* Uptime */}
+      <section>
+        <h2><T id="uptime.heading" values={{ days: String(grid.length) }} /></h2>
+        <div className="uptime" aria-hidden="true">
+          {grid.map((up, idx) => (
+            <span key={idx} className={up ? 'day up' : 'day down'} />
+          ))}
+        </div>
+        <p className="muted"><T id="uptime.percent" values={{ percent: String(pct) }} /></p>
+      </section>
+
+      {/* Components */}
+      <section>
+        <h2><T id="components.heading" /></h2>
+        {components.length === 0 ? (
+          <p className="muted"><T id="components.empty" /></p>
+        ) : (
+          <ul className="components">
+            {components.map((c) => (
+              <li key={c.id}>
+                <span>{c.name}</span>
+                <span className={`pill pill--${c.status}`}><T id={`comp.status.${c.status}`} /></span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      {/* Incidents */}
+      <section>
+        <h2><T id="incidents.heading" /></h2>
+        {incidents.length === 0 ? (
+          <p className="muted"><T id="incidents.none" /></p>
+        ) : (
+          <ul className="incidents">
+            {incidents.map((inc) => (
+              <li key={inc.id} className={`incident impact--${inc.impact}`}>
+                <div className="incident-head">
+                  <strong>{inc.title}</strong>
+                  <span className="pill"><T id={`impact.${inc.impact}`} /></span>
+                  <span className="pill"><T id={`status.${inc.status}`} /></span>
+                </div>
+                <p className="muted">
+                  <T id="incident.started" values={{ when: fmtDate(inc.startedAt) }} />
+                  {' · '}
+                  {inc.resolvedAt == null
+                    ? <T id="incident.ongoing" />
+                    : <T id="incident.resolved" values={{ when: fmtDate(inc.resolvedAt) }} />}
+                </p>
+                {updatesFor(inc.id).length > 0 ? (
+                  <ul className="timeline">
+                    {updatesFor(inc.id).map((u) => (
+                      <li key={u.id}>
+                        <span className="ts">{fmtDate(u.createdAt)}</span>
+                        <span className="pill"><T id={`status.${u.status}`} /></span>
+                        <span>{u.body}</span>
+                      </li>
+                    ))}
+                  </ul>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+    </main>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-status",
+  "kind": "web",
+  "summary": "A public status page — a clean live-useSubscription showcase. An SSR shell bakes the current incidents + components into the first paint (crawlable), then upgrades to live: the banner, 90-day uptime grid and incident timeline update within seconds when an operator posts, with no polling. Pairs with the api-status backend. Bilingual (en/de), no auth (it must stay up when the product is down).",
+  "tags": ["web", "frontend", "status-page", "live", "useSubscription", "ssr", "uptime"]
+}

package/templates/apps/frontend-status/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/mobile-app/README.md

@@ -0,0 +1,58 @@
+# {{capProjectName}} — mobile (Expo + Voltro)
+
+An [Expo](https://expo.dev) (React Native) app that is the **third consumer** of
+your Voltro api — the same typed hooks you use on the web (`useSubscription` /
+`useMutation`), offline-first by default, with typed deep links and device
+registration for push.
+
+> **Expo owns the dev loop, not `voltro dev`.** This app is started with
+> `expo start` / `expo run:ios`, not `voltro dev`. The sibling api still runs
+> under `voltro dev`; this app connects to it over the network.
+
+## Run it
+
+```sh
+# 1. In one shell — the api (scaffold it with --api=api-backend):
+voltro dev
+
+# 2. Point this app at the api. On a simulator/device use your machine's LAN
+#    address, NOT localhost:
+export EXPO_PUBLIC_API_URL="http://192.168.x.x:4000"
+
+# 3. In another shell — the app:
+pnpm ios        # or: pnpm android · pnpm start (Expo Go)
+```
+
+## What's here
+
+| Path | What |
+|---|---|
+| `src/lib/deeplinks.ts` | the typed deep-link table + pure resolver (**tested**) |
+| `src/lib/sync.ts` | the background-sync decision layer (**tested**) |
+| `src/lib/notifications.ts` | build a `_voltro_devices` row from a push token (**tested**) |
+| `src/client.ts` | the Voltro client + the **M0 seam** (read its header) |
+| `src/persistence.ts` | RN key-value with the secure/plain split |
+| `src/app/*` | Expo Router screens (list, detail, settings) |
+| `voltro.mobile.ts` | which api(s) this app consumes |
+
+## Honest status (read before you expect the loop to work on a device)
+
+The **pure logic** in `src/lib/*` is real and unit-tested (`pnpm test`). The
+**client wiring** — building the runtime + subscription cache + rpc client that
+the hooks read — is **not yet implemented for React Native**: on the web it lives
+in `@voltro/web`'s web-coupled boot. Wiring an RN-safe equivalent is Phase **M0**
+in the framework's mobile plan (`plans/open/mobile/`). Until it lands,
+`buildApiHandles()` in `src/client.ts` returns an empty map and the screens show
+their loading state — deliberately, not a crash. `src/client.ts`'s header spells
+out exactly what M0 must build.
+
+The tests here run without a simulator. Booting the app on a device (`expo
+run:ios`) is your Expo/EAS CI step — there is no iOS/Android toolchain in the
+framework repo's sandbox.
+
+## Tests
+
+```sh
+pnpm test        # the pure lib — no simulator needed
+pnpm typecheck   # tsc over the app (needs Expo/RN types installed)
+```

package/templates/apps/mobile-app/app.config.ts

@@ -0,0 +1,33 @@
+// Expo app config for the {{projectName}} mobile app.
+//
+// NOTE: this is EXPO's config, NOT Voltro's `type: 'web'|'api'` app.config. A
+// mobile app is not run by `voltro dev` — Expo owns Metro and the simulator
+// (`expo start` / `expo run:ios`). The sibling api this app consumes still runs
+// under `voltro dev`; the app connects to it over HTTP/WebSocket via
+// `EXPO_PUBLIC_API_URL` (see src/client.ts).
+//
+// `scheme` is the custom URL scheme that makes deep links open THIS app
+// (`{{appName}}://orders/42`). Keep it in sync with the deep-link table in
+// src/lib/deeplinks.ts — `voltro mobile doctor` (planned) checks this.
+import type { ExpoConfig } from 'expo/config'
+
+const config: ExpoConfig = {
+  name: '{{capProjectName}}{{capAppName}}',
+  slug: '{{projectName}}-{{appName}}',
+  scheme: '{{appName}}',
+  version: '0.0.0',
+  orientation: 'portrait',
+  userInterfaceStyle: 'automatic',
+  newArchEnabled: true,
+  ios: { supportsTablet: true, bundleIdentifier: 'com.{{projectName}}.{{appName}}' },
+  android: { package: 'com.{{projectName}}.{{appName}}' },
+  plugins: [
+    'expo-router',
+    'expo-secure-store',
+    // Add 'expo-notifications' here once you wire the push pipeline
+    // (see plans/open/mobile/02-push-pipeline.md).
+  ],
+  experiments: { typedRoutes: true },
+}
+
+export default config

package/templates/apps/mobile-app/babel.config.js

@@ -0,0 +1,5 @@
+// Expo's Babel preset — required for expo-router + React Native transforms.
+module.exports = function babel(api) {
+  api.cache(true)
+  return { presets: ['babel-preset-expo'] }
+}

package/templates/apps/mobile-app/metro.config.js

@@ -0,0 +1,20 @@
+// Metro config — the ONLY Voltro-specific wrinkle in a monorepo: watch the
+// workspace root so `@voltro/*` (and the sibling api's generated types) resolve
+// from the repo, not just this app's node_modules. In a standalone (non-
+// monorepo) app you can delete this file; Expo's default config is enough.
+const { getDefaultConfig } = require('expo/metro-config')
+const path = require('node:path')
+
+const projectRoot = __dirname
+const workspaceRoot = path.resolve(projectRoot, '../../..')
+
+const config = getDefaultConfig(projectRoot)
+config.watchFolders = [workspaceRoot]
+config.resolver.nodeModulesPaths = [
+  path.resolve(projectRoot, 'node_modules'),
+  path.resolve(workspaceRoot, 'node_modules'),
+]
+// Prefer a single physical React across the workspace (RN + web share one).
+config.resolver.disableHierarchicalLookup = true
+
+module.exports = config

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

@@ -0,0 +1,33 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "main": "expo-router/entry",
+  "scripts": {
+    "start": "expo start",
+    "ios": "expo run:ios",
+    "android": "expo run:android",
+    "web": "expo start --web",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@voltro/client": "0.30.0",
+    "@voltro/react-native": "0.30.0",
+    "expo": "^52.0.0",
+    "expo-constants": "~17.0.0",
+    "expo-linking": "~7.0.0",
+    "expo-router": "~4.0.0",
+    "expo-secure-store": "~14.0.0",
+    "expo-status-bar": "~2.0.0",
+    "@react-native-async-storage/async-storage": "1.23.1",
+    "@react-native-community/netinfo": "11.4.1",
+    "react": "^19.0.0",
+    "react-native": "0.76.5"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/mobile-app/src/app/_layout.tsx

@@ -0,0 +1,61 @@
+// Root layout — wires the Voltro client provider, deep-link routing, and a
+// connection banner around the whole app.
+//
+// NOTE: `buildApiHandles()` is the M0 seam (see ../client.ts). Until the RN boot
+// helper lands it returns an empty map, so the hooks render their loading state
+// rather than live data — deliberately honest, not a crash.
+import { useEffect, useState } from 'react'
+import { Stack, useRouter } from 'expo-router'
+import * as Linking from 'expo-linking'
+import { StatusBar } from 'expo-status-bar'
+import { FrameworkRuntimesProvider, type ApiHandle } from '@voltro/client'
+import { useMobileConnectionStatus } from '@voltro/react-native'
+import { Text, View } from 'react-native'
+import { buildApiHandles } from '../client'
+import { handleDeepLink, makeDeepLinks } from '../lib/deeplinks'
+
+function ConnectionBanner() {
+  const { status } = useMobileConnectionStatus()
+  if (status === 'connected') return null
+  return (
+    <View style={{ backgroundColor: status === 'offline' ? '#b91c1c' : '#b45309', padding: 8 }}>
+      <Text style={{ color: 'white', textAlign: 'center' }}>
+        {status === 'offline' ? 'Offline — changes will sync when you reconnect' : 'Reconnecting…'}
+      </Text>
+    </View>
+  )
+}
+
+export default function RootLayout() {
+  // Build the api handle map once on mount (async — it opens the WebSocket via
+  // @voltro/client's buildApiRuntime). Empty until it resolves; the hooks render
+  // their loading state meanwhile.
+  const [apis, setApis] = useState<ReadonlyMap<string, ApiHandle>>(() => new Map())
+  useEffect(() => {
+    let live = true
+    void buildApiHandles().then((map) => { if (live) setApis(map) })
+    return () => { live = false }
+  }, [])
+  const router = useRouter()
+
+  // Route inbound URLs (universal links, custom scheme, push taps) through the
+  // ONE typed link table — the same `matchFirstDeepLink` path push will use.
+  useEffect(() => {
+    const links = makeDeepLinks((href) => router.push(href as never))
+    const sub = Linking.addEventListener('url', ({ url }) => {
+      handleDeepLink(links, url)
+    })
+    void Linking.getInitialURL().then((url) => {
+      if (url) handleDeepLink(links, url)
+    })
+    return () => sub.remove()
+  }, [router])
+
+  return (
+    <FrameworkRuntimesProvider apis={apis}>
+      <StatusBar style="auto" />
+      <ConnectionBanner />
+      <Stack screenOptions={{ headerTitle: '{{capProjectName}}' }} />
+    </FrameworkRuntimesProvider>
+  )
+}