@voltro/cli 0.38.0 → 0.39.1

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

@@ -12,16 +12,16 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.38.0",
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@{{projectName}}/api": "0.39.1",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.38.0",
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@{{projectName}}/api": "0.39.1",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-ssr-api/package.json

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.38.0",
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@{{projectName}}/api": "0.39.1",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-static-blog/package.json

@@ -12,16 +12,16 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.38.0",
-    "@voltro/cli": "0.38.0",
-    "@voltro/client": "0.38.0",
-    "@voltro/env": "0.38.0",
-    "@voltro/i18n": "0.38.0",
-    "@voltro/ui-shadcn": "0.38.0",
-    "@voltro/web": "0.38.0",
+    "@{{projectName}}/api": "0.39.1",
+    "@voltro/cli": "0.39.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/env": "0.39.1",
+    "@voltro/i18n": "0.39.1",
+    "@voltro/ui-shadcn": "0.39.1",
+    "@voltro/web": "0.39.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.38.0",
+    "@voltro/devtools": "0.39.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/mobile-app/README.md

@@ -15,12 +15,14 @@ registration for push.
 # 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:
+# 2. In another shell — the app. `pnpm ios` runs `voltro codegen` first, which
+#    writes this app's api binding from voltro.mobile.ts.
 pnpm ios        # or: pnpm android · pnpm start (Expo Go)
+
+# The ws URL is derived from the host running Metro, so a device on the same
+# wifi reaches your machine. Override it for a deployed api:
+#   export EXPO_PUBLIC_API_WS_URL="wss://api.example.com/ws"
+#   export EXPO_PUBLIC_API_PORT=4000   # if your api is not on 4000
 ```
 
 ## What's here
@@ -31,25 +33,32 @@ pnpm ios        # or: pnpm android · pnpm start (Expo Go)
 | `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/client.ts` | the Voltro client: generated api binding + supervisor + persistence |
 | `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 client is wired: `voltro codegen` writes this app's api binding from
+`voltro.mobile.ts`, and `src/client.ts` connects it through the SAME reconnect
+supervisor the web client uses, with persisted stores hydrated before the first
+render. The start scripts run codegen, so `pnpm ios` needs no separate step.
+
+What is NOT verified in this repository is the one thing only a device can tell
+you: that the loop runs under Metro on a simulator or a phone. There is no
+iOS/Android toolchain in the framework's sandbox, so booting the app is your
+Expo/EAS CI step. The unit tests here run without one and deliberately do not
+pretend otherwise.
+
+Two things to check first if a device shows loading forever:
 
-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.
+- **`localhost` on a phone is the phone.** The ws URL is derived from the host
+  running Metro (`resolveDevWsUrl`), which works on a device on the same wifi.
+  Set `EXPO_PUBLIC_API_WS_URL` to point somewhere else.
+- **The api must be running.** `voltro dev` in the project root boots it; this
+  app is deliberately not part of that orchestration, because Expo owns its own
+  dev server.
 
 ## Tests
 
@@ -57,3 +66,18 @@ framework repo's sandbox.
 pnpm test        # the pure lib — no simulator needed
 pnpm typecheck   # tsc over the app (needs Expo/RN types installed)
 ```
+
+### Why this app's `tsconfig.json` overrides Expo's base
+
+Three overrides, each for a reason that shows up as a hard error without it:
+
+- **`moduleResolution: "bundler"`** — Expo's base sets `node` (node10), which
+  TypeScript 6 rejects outright. `bundler` is also the honest description of
+  Metro.
+- **`types: ["node", "react"]`** — `process.env.EXPO_PUBLIC_*` is Expo's own
+  idiom for build-time config, and `process` needs a type. Listing the types
+  explicitly keeps everything else out.
+- **`@types/node` as a devDependency** — the other half of the same line.
+
+Run `pnpm typecheck` after `voltro codegen`, in that order: the generated api
+binding is a real import and the app does not typecheck without it.

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

@@ -4,7 +4,7 @@
 // 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).
+// `EXPO_PUBLIC_API_WS_URL` / `EXPO_PUBLIC_API_PORT` (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

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

@@ -4,32 +4,36 @@
   "private": true,
   "main": "expo-router/entry",
   "scripts": {
-    "start": "expo start",
-    "ios": "expo run:ios",
-    "android": "expo run:android",
-    "web": "expo start --web",
+    "start": "voltro codegen . && expo start",
+    "ios": "voltro codegen . && expo run:ios",
+    "android": "voltro codegen . && expo run:android",
+    "web": "voltro codegen . && expo start --web",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "codegen": "voltro codegen ."
   },
   "dependencies": {
-    "@voltro/client": "0.38.0",
-    "@voltro/react-native": "0.38.0",
+    "@react-native-async-storage/async-storage": "1.23.1",
+    "@react-native-community/netinfo": "11.4.1",
+    "@voltro/client": "0.39.1",
+    "@voltro/react-native": "0.39.1",
+    "@{{projectName}}/api": "0.39.1",
     "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-splash-screen": "~0.29.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": {
-    "@{{projectName}}/api": "0.38.0",
+    "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
-    "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
+    "@voltro/cli": "0.39.1",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }
 }

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

@@ -1,21 +1,35 @@
-// Root layout — wires the Voltro client provider, deep-link routing, and a
-// connection banner around the whole app.
+// Root layout — wires the Voltro client, 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.
+// The boot ORDER here is load-bearing, and it is the one thing to preserve if
+// you rewrite this file:
+//
+//   1. hydrate persisted stores, THEN install them as the backing store;
+//   2. only then render the app.
+//
+// A store reads during render and a render cannot await, so rendering first
+// shows empty state and flickers into the saved state a frame later. The splash
+// screen stays up until step 1 finishes — that is what it is for.
+//
+// Connecting is deliberately NOT part of that gate. The app must open offline.
 import { useEffect, useState } from 'react'
 import { Stack, useRouter } from 'expo-router'
 import * as Linking from 'expo-linking'
+import * as SplashScreen from 'expo-splash-screen'
 import { StatusBar } from 'expo-status-bar'
-import { FrameworkRuntimesProvider, type ApiHandle } from '@voltro/client'
+import { FrameworkRuntimesProvider, type ApiHandle, type ResolvedClient } from '@voltro/client'
 import { useMobileConnectionStatus } from '@voltro/react-native'
 import { Text, View } from 'react-native'
-import { buildApiHandles } from '../client'
+import { connectApis, handlesFor, onlineSource, preparePersistence } from '../client'
 import { handleDeepLink, makeDeepLinks } from '../lib/deeplinks'
 
+void SplashScreen.preventAutoHideAsync()
+
 function ConnectionBanner() {
-  const { status } = useMobileConnectionStatus()
+  // Reachability comes from NetInfo. The default source reads `navigator.onLine`,
+  // which React Native does not have — so on a device it would answer "online"
+  // forever, including in airplane mode.
+  const { status } = useMobileConnectionStatus({ onlineSource })
   if (status === 'connected') return null
   return (
     <View style={{ backgroundColor: status === 'offline' ? '#b91c1c' : '#b45309', padding: 8 }}>
@@ -27,16 +41,31 @@ function ConnectionBanner() {
 }
 
 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 [ready, setReady] = useState(false)
   const [apis, setApis] = useState<ReadonlyMap<string, ApiHandle>>(() => new Map())
+  const router = useRouter()
+
+  // 1. Persisted state, before anything renders.
   useEffect(() => {
     let live = true
-    void buildApiHandles().then((map) => { if (live) setApis(map) })
+    void preparePersistence()
+      .catch(() => { /* a device with no readable storage still gets an app */ })
+      .finally(() => {
+        if (!live) return
+        setReady(true)
+        void SplashScreen.hideAsync()
+      })
     return () => { live = false }
   }, [])
-  const router = useRouter()
+
+  // 2. Connect, and keep connected. The supervisor re-dials with backoff; a
+  //    dropped socket needs no handling here.
+  useEffect(() => {
+    const supervisor = connectApis((clients: ReadonlyMap<string, ResolvedClient>) => {
+      setApis(handlesFor(clients))
+    })
+    return () => supervisor.dispose()
+  }, [])
 
   // Route inbound URLs (universal links, custom scheme, push taps) through the
   // ONE typed link table — the same `matchFirstDeepLink` path push will use.
@@ -51,6 +80,8 @@ export default function RootLayout() {
     return () => sub.remove()
   }, [router])
 
+  if (!ready) return null
+
   return (
     <FrameworkRuntimesProvider apis={apis}>
       <StatusBar style="auto" />

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

@@ -3,7 +3,7 @@
 // The SAME hooks as the web frontend: `useSubscription('notes.list')` streams
 // the server-side query; `useMutation('notes.create')` writes it. When the
 // mutation lands, the server pushes a delta and this list re-renders — no
-// refetch, no polling. (Requires the M0 client boot; see ../client.ts.)
+// refetch, no polling.
 //
 // Both come from `../lib/api`, which binds them ONCE to the api's generated
 // procedure map — so the tag autocompletes, a typo is a compile error, and the

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

@@ -3,9 +3,12 @@ import { useState } from 'react'
 import { Pressable, Text, View } from 'react-native'
 import { useMobileConnectionStatus } from '@voltro/react-native'
 import { buildDeviceRegistration } from '../lib/notifications'
+import { onlineSource } from '../client'
 
 export default function Settings() {
-  const { status, reportSuccess, reportFailure } = useMobileConnectionStatus()
+  // Same injected source as the banner in _layout: the default reads
+  // `navigator.onLine`, which React Native does not have.
+  const { status, reportSuccess, reportFailure } = useMobileConnectionStatus({ onlineSource })
   const [registered, setRegistered] = useState<string | null>(null)
 
   return (