@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/reference.md

@@ -13,10 +13,13 @@ _The client-side hook surface, grouped by purpose._
 
 The web side of a Voltro app talks to API apps through React hooks. Data hooks are keyed by API name and RPC tag; routing hooks are provided by `@voltro/web`.
 
+App code should reach for the **typed binding** rather than the tag-taking hooks directly: [`createHooks(apiName)`](/docs/reference/hooks-data) takes the api's generated `AppProcedures` map and returns `useSubscription` / `useMutation` / `useAction` whose tag is a literal union and whose input and output types are inferred — so a typo'd tag is a compile error and the result needs no annotation. Bind it once per api in `src/lib/api.ts`. The tag-taking forms documented below are the primitive underneath, for code that only learns the tag at runtime.
+
 ## Data Hooks
 
 | Hook | Purpose |
 |---|---|
+| [`createHooks`](/docs/reference/hooks-data) | Bind the typed hook surface for one api — the recommended app-facing entry point. |
 | [`useSubscription`](/docs/reference/hooks-data) | Subscribe to a reactive query (`*.query.ts`). |
 | [`useMutation`](/docs/reference/hooks-data) | Run an atomic write (`*.mutation.ts`). |
 | [`useAction`](/docs/reference/hooks-data) | Run a unary non-transactional action (`*.action.ts`). |
@@ -112,6 +115,51 @@ _useSubscription, useMutation, useAction, useWorkflow, workflow status hooks, us
 
 Data hooks from `@voltro/client` are keyed by **api name** plus **RPC tag**. The tags come from descriptors discovered in the API app.
 
+## `createHooks(apiName)` — the typed hook binding
+
+`createHooks` turns the api's generated procedure map into hooks whose **RPC tag is a literal union** and whose **input and output types are inferred**. It is the recommended way to call an api from app code.
+
+Codegen emits `AppProcedures` into the api's `rpcGroup.generated.ts` — a type-level map of every tag (yours and every plugin's) to the descriptor behind it. Bind it once, at module scope, next to the rest of your api glue:
+
+```ts
+// src/lib/api.ts — one file, one line, once per app
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@app/api/rpcGroup'
+
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')
+```
+
+`'app'` is the key this web app gave the api in `app.config.ts` → `apis`. It is now spelled exactly once per app instead of once per call site:
+
+```tsx
+import { useSubscription, useMutation } from '../lib/api'
+
+const { data } = useSubscription('notes.list')   // ReadonlyArray<Note>, inferred
+const create = useMutation('notes.create')       // input + output inferred
+```
+
+What the compiler catches that it could not before:
+
+| Mistake | Before | Now |
+|---|---|---|
+| Typo in the tag (`'notes.lst'`) | Runtime dev-console error | Compile error |
+| Wrong hook for the kind (a mutation passed to `useSubscription`) | Runtime `console.error` | Compile error |
+| Missing a required input field | Request sent with `undefined` | Compile error |
+| Wrongly-shaped input | Server-side decode failure | Compile error |
+| Result type annotation disagreeing with the server | Never detected | Impossible — there is no annotation |
+
+The result keeps every narrowing rule of the untyped hook: `loading` still discriminates `data`, `fallback` / `initialSnapshot` still remove the branch, and only a **dynamic** `skip` adds the `idle` state.
+
+Row types include the auto-optimistic marker the client adds, so `row.optimistic` type-checks on a live list without a hand-written row mirror.
+
+**Destructure the result** — do not export the object and call `api.useSubscription(...)`. `react-hooks/rules-of-hooks` only recognises a member call as a hook when the object is PascalCase, so a lowercase namespace silently switches off rules-of-hooks and exhaustive-deps at every call site.
+
+`import type` is erased at build time, so the binding adds nothing to the browser bundle.
+
+**`rpcGroup.generated.ts` is written by codegen**, so a tree that has never booted does not have it yet and `tsc` reports `Cannot find module '@app/api/rpcGroup'`. `voltro dev` generates it on boot; run `voltro codegen` once for a fresh clone or a CI job that only typechecks. The scaffolded api templates do this in their own `typecheck` script, and `pnpm -r` runs the api before anything that depends on it.
+
+The tag-taking hooks below are the primitive underneath. Reach for them when the tag is only known at runtime — plugin web bindings and libraries shipped against an unknown app — not in app code.
+
 ## `useSubscription(apiName, rpcTag, input?, options?)`
 
 Subscribes to a reactive `defineQuery` RPC.
@@ -1101,13 +1149,18 @@ If the work is "do X once and finish", it's a seed. If it's "keep X running unti
 <!-- source: en/reference/templates.md -->
 ## App templates
 
-_The scaffolding catalogue — every api / web / serverless template, what it demonstrates, and when to pick it._
+_The scaffolding catalogue — the api / web / serverless / mobile templates, what each demonstrates, and when to pick it._
 
 Every template is a dogfooded, runnable reference. Scaffold one with
 `voltro create-project --api <id> --web <id>` (or `voltro add-app <name>
---template <id>`), and run `voltro list-templates` for the live list.
+--template <id>`).
+
+**`voltro list-templates` is the authority, not this page.** It prints the
+templates your installed CLI actually ships — there are dozens — while the
+tables below cover the ones worth a paragraph of explanation. If an id appears
+in the command's output and not here, it exists and works.
 
-Templates come in **three kinds**, matching the three things you deploy:
+Templates come in **four kinds**, matching the four things you deploy:
 
 - **`api`** — a long-running backend (`app.config` `type: 'api'`).
 - **`web`** — a frontend (`type: 'web'`); gets a dev-server port.
@@ -1115,6 +1168,10 @@ Templates come in **three kinds**, matching the three things you deploy:
   functions](/docs/deployment/serverless-functions) shipped on their own with
   `voltro serverless`. No long-running server, no port — add it to a project
   with `voltro add-app`.
+- **`mobile`** — an Expo (React Native) app (`mobile-app`), scaffolded with
+  `--mobile`. Expo owns its own dev loop, so it is not part of `voltro dev`; the
+  sibling api still is, and the app consumes it over the network with the same
+  typed hooks the web app uses.
 
 ## API backends (`kind: api`)