@lunora/cli 1.0.0-alpha.42 → 1.0.0-alpha.420

package/skills/lunora-realtime/SKILL.md

@@ -1,37 +1,52 @@
 ---
 name: lunora-realtime
-description: Wires Lunora's live data into a client. Use for `LunoraClient`/`LunoraProvider`,
-    reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates,
-    pagination, connection status, the React/Vue/Solid/Svelte adapters, and the
-    `@lunora/db` TanStack binding.
+description: Wires Lunora's live data into a client app. Covers `LunoraClient` and the per-framework provider, reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates, `usePaginatedQuery`, `shardKey` routing, connection status, presence, the React/Vue/Solid/Svelte/Angular/React Native adapters, and the `@lunora/db` TanStack DB binding. Use when building UI that reads or writes Lunora functions, when asked to "show live data", "make this update in real time", "add optimistic updates", "add infinite scroll/pagination", or "show offline/reconnecting state", when editing components that import `@lunora/react`/`vue`/`solid`/`svelte`/`angular`/`react-native` or `lunorash/client`, when a live query stays `undefined`, freezes, or doesn't update, or when choosing between a live query, a stream, a live topic (`defineLiveStream`, `useLiveTopic`, `ctx.live.publish`, SSE), a whisper, a room and a socket, such as "push an event to the browser" or "notify the page when X happens".
 ---
 
 # Lunora Realtime
 
 Consume Lunora functions reactively from the client. Queries are live
-subscriptions over WebSocket — a `useQuery` re-renders the instant a mutation
+subscriptions over WebSocket — a `useQuery` re-renders as soon as a mutation
 changes the rows it reads — and mutations can paint optimistically with
 automatic rollback.
 
-## When to Use
+## Choosing a Channel
 
-- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
-- Adding optimistic updates, pagination, or presence to the UI.
-- Choosing between live hooks and the `@lunora/db` collection layer.
+Decide by what you are sending. If the client could get it by running a query,
+use a live query: it is typed, runs under the caller's identity, and works across
+shards. Reach past it only for the rest.
+
+| You want                                           | Use                                                    |
+| -------------------------------------------------- | ------------------------------------------------------ |
+| Rows that stay fresh                               | `useQuery` (WebSocket, typed through `api.*`)          |
+| A write / a side effect                            | `useMutation` / `useAction`                            |
+| Chunks of one long call (model tokens)             | `query.stream()` + `useStream` (`durable` to resume)   |
+| Chunks of one HTTP request                         | `httpRoute.get(path).stream()` + `useHttpStream`       |
+| A server-published event that is not a row         | live topic: `defineLiveStream` + `useLiveTopic`        |
+| A client-to-clients ephemeral message (cursors)    | whisper (`client.whisper`; authorize with `onWhisper`) |
+| A room with server join / message / leave handlers | `defineRoom` + `client.connectRoom`                    |
+| A dedicated socket at your own path                | `defineWebSocket` + `client.connectWebSocket(path)`    |
+| Who is online                                      | `usePresence`                                          |
+
+Live topics are typed from their declaration: each topic's key and payload are
+validators on the stream, and codegen emits `_generated/live.ts` with a typed
+reference per topic. Full guide: the "Choosing a data channel" docs page.
 
 ## When Not to Use
 
 - Writing the server functions themselves — that's `lunora-functions`.
 - Initial project/provider scaffolding — that's `lunora-quickstart`.
+- Sign-in UI and the `Authenticated` gates — that's `lunora-setup-auth`.
 
 ## Provider Setup
 
-Create the `LunoraClient` once at module scope and wrap the app. The client owns
-the WebSocket, the optimistic cache, and the offline queue.
+Create the `LunoraClient` once at module scope; it owns the WebSocket, the
+optimistic cache, and the offline queue, so creating it inside a component
+reopens the socket on every render.
 
 ```tsx
-import { LunoraClient } from "@lunora/client";
 import { LunoraProvider } from "@lunora/react";
+import { LunoraClient } from "lunorash/client";
 
 const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin;
 const client = new LunoraClient({ url });
@@ -39,80 +54,97 @@ const client = new LunoraClient({ url });
 // <LunoraProvider client={client}>…</LunoraProvider>
 ```
 
-Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
-`@lunora/svelte`; the hook names and semantics below mirror across them.
+The adapters differ in how they register the client and name their primitives:
+
+| Package                | Register the client                                          | Live read / write                              |
+| ---------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
+| `@lunora/react`        | `<LunoraProvider client={client}>`                           | `useQuery` / `useMutation`                     |
+| `@lunora/vue`          | `app.use(createLunora(client))` (or `provideLunora(client)`) | `useQuery` / `useMutation`                     |
+| `@lunora/solid`        | `<LunoraProvider client={client}>`                           | `createQuery` / `createMutation`               |
+| `@lunora/svelte`       | `setLunoraClient(client)` in the root layout                 | `query` / `mutation` stores                    |
+| `@lunora/angular`      | `provideLunora()` in `ApplicationConfig`                     | `liveQuery` / `mutate`, `injectLunoraClient()` |
+| `@lunora/react-native` | `createLunoraClient({ url, storage })` + `LunoraProvider`    | re-exports `@lunora/react` hooks               |
+
+The rest of this skill uses the React names; the others mirror the same
+semantics (`usePaginatedQuery` → `createPaginatedQuery` / `paginatedQuery`,
+`useConnectionStatus` → `createConnectionStatus` / `connectionStatus`, …).
+React Native passes `storage: AsyncStorage` so the offline queue survives a
+restart; `@lunora/react-native/auth` bridges a better-auth Expo session.
+`@lunora/astro` and `@lunora/nuxt` (Nitro) integrate Lunora into the SSR server.
 
 ## Live Queries
 
-`useQuery(reference, args)` opens a subscription and returns the value, or
-`undefined` while it loads. The reference comes from codegen
-(`api.<file>.<name>`).
+`useQuery(reference, args, options?)` opens a subscription and returns the
+value, or `undefined` while it loads. References come from codegen and are
+typed end to end, so no cast is needed:
 
 ```tsx
 import { useQuery } from "@lunora/react";
 
-import { api } from "../../lunora/_generated/api";
-import type { Doc } from "../../lunora/_generated/dataModel";
+import { api } from "../lunora/_generated/api";
 
-const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
+const todos = useQuery(api.todos.list, {});
+const messages = useQuery(api.messages.list, { channelId }, { shardKey: channelId, onError: report });
 ```
 
-- `undefined` means "loading" — render a skeleton/spinner for it.
-- The subscription tears down on unmount and re-runs only when `args` change or
-  the underlying rows change. Keep `args` narrow so a write elsewhere doesn't
-  re-push unrelated data (see `lunora-performance-audit`).
-- `useSubscription` is the lower-level primitive for streaming subscriptions;
-  `usePreloadedQuery` + `lunoraQueryOptions` support SSR/preload handoff via
-  `@lunora/react/server`.
+- `undefined` means loading and `[]` means loaded-and-empty; branch on both.
+- Pass `"skip"` as `args` to disable the query (no network call, no
+  subscription) — e.g. until a required id is known.
+- Pass `onError` to see a server-pushed error (an RLS denial, a query that starts
+  throwing). Without it the error is dropped and the value silently freezes at
+  its last good result.
+- `shardKey`: for a `.shardBy(...)` table, pin every read and write to the
+  shard's key (`{ shardKey: channelId }` on both `useQuery` and the mutation
+  call). Without it the runtime has to fan out across every shard.
+- The subscription re-runs only when `args` or the rows it read change. Keep
+  `args` narrow so unrelated writes don't re-push data (see
+  `lunora-performance-audit`).
+- `useSubscription` is the push-only variant (no initial HTTP fetch) returning
+  `{ data, error }`. For SSR, `@lunora/react/server` exports `preloadQuery`,
+  `fetchQuery`, and `lunoraQueryOptions`; hand the result to
+  `usePreloadedQuery` on the client.
+- References in folders are nested: `lunora/billing/invoices.ts` →
+  `api.billing.invoices.<fn>`. Client code only ever imports `api`;
+  `internal` functions are not callable from the client.
 
 ## Authorization & Live Queries
 
-Subscriptions re-run the query handler **server-side under anonymous
-identity**. The one-shot `fetch` RPC behind the initial load carries the
-caller's identity, but the live WebSocket channel (the subscription seed and
-every write-driven refresh) does not — it evaluates as anonymous.
-
-This matters for any query that authorizes or filters on the authenticated
-user:
+Live queries are identity-aware. At the WebSocket upgrade the runtime stamps
+the caller's verified identity onto the socket, and every subscription re-run
+executes under that identity, so:
 
-- A query guarded by `.use(rls(...))` or one that reads `ctx.auth.userId`
-  directly returns the user's rows on the **initial** HTTP fetch, but its
-  **live** updates evaluate anonymously and may resolve to an empty/denied
-  set.
-- This **fails closed** — the live channel shows _less_ data, never another
-  user's data, so there is no leak. But it is a correctness caveat: the
-  initial render and the live updates can disagree.
+- `.use(rls(...))` and `ctx.auth.userId` behave the same in a subscription as in
+  a one-shot read. Shape subscriptions AND-merge their predicate with the
+  table's RLS read policy.
+- An anonymous socket carries no identity, so an RLS/`ctx.auth` query fails
+  closed (empty or denied) rather than leaking rows.
+- When the credential carries an expiry, the server sends `TOKEN_EXPIRED` and
+  closes with code `4001`. `LunoraClient` reconnects and re-resolves identity
+  automatically; surface it in the UI only if a re-login is required.
 
-The supported pattern today is to scope per-user data **outside** of
-`ctx.auth` inside a subscribed query:
-
-- Partition the data by shard with `.shardBy(userId)` (or tenant/room), so the
-  subscription is already scoped to the right state, or
-- Pass the identifier as an **explicit query arg**
-  (`useQuery(api.todos.list, { userId })`) and filter on the arg rather than on
-  `ctx.auth`.
-
-Reserve `rls()` / `ctx.auth`-based filtering for non-subscribed reads (one-shot
-actions/queries) where identity is always present.
+Use `.shardBy(...)` and narrow args for performance, `rls()` / `ctx.auth` for
+authorization. They compose.
 
 ## Mutations + Optimistic Updates
 
-`useMutation(reference)` returns `{ mutate, pending }`. Pass an `optimistic`
-callback to paint the next state immediately; if the server rejects the call the
-runtime rolls the cache back automatically.
+`useMutation(reference)` returns `{ mutate, pending, data, error, reset }`.
+Destructure it — the hook result itself isn't callable. `mutate` returns a
+promise that rejects on failure. Pass `optimisticUpdate` to paint the next state
+immediately; if the server rejects the call the cache rolls back.
 
 ```tsx
 import { useMutation } from "@lunora/react";
 
-import type { Doc, Id } from "../../lunora/_generated/dataModel";
+import { api } from "../lunora/_generated/api";
+import type { Doc, Id } from "../lunora/_generated/dataModel";
 
 const { mutate: add, pending } = useMutation(api.todos.add);
 
 await add(
     { text },
     {
-        optimistic: (current) => {
-            const list = (current as Doc<"todos">[] | undefined) ?? [];
+        optimisticUpdate: (store) => {
+            const list = store.getQuery(api.todos.list, {}) ?? [];
             const provisional: Doc<"todos"> = {
                 _id: `optimistic_${Date.now()}` as Id<"todos">,
                 _creationTime: Date.now(),
@@ -120,58 +152,146 @@ await add(
                 done: false,
                 createdAt: Date.now(),
             };
-            return [provisional, ...list];
+            store.setQuery(api.todos.list, {}, [provisional, ...list]);
         },
     },
 );
 ```
 
-- The `optimistic` callback receives the current cached value and returns the
-  provisional one. When the server delta arrives it replaces the optimistic
-  entry; on failure the cache reverts.
-- `pending` is `true` while the call is in flight — disable the submit button
-  with it.
-- **Offline queue:** mutations made while disconnected are queued by
-  `LunoraClient` and replayed on reconnect (client-id-keyed, so they aren't
-  double-applied).
+- `optimisticUpdate` names the query it patches because nothing can infer that
+  `todos.add` affects `todos.list`. `store.getAllQueries(fn)` lists every
+  subscribed args variant of a query so you can patch each one.
+- The provisional row must match the query's element shape, including
+  `_id`/`_creationTime`, or the UI flickers when the real row lands.
+- The per-call `optimistic: (current) => next` shortcut only patches a
+  subscription under the mutation's own reference and args (a counter, a doc by
+  id). For the add-updates-list shape above it is a silent no-op.
+- `pending` stays `true` until every overlapping call from this hook settles;
+  use it to disable the submit button.
+- Offline, mutations are queued by `LunoraClient` and replayed on reconnect,
+  keyed by client id so they aren't applied twice.
 
 ## Pagination, Connection, Presence
 
-- `usePaginatedQuery` / `useInfiniteQuery` — cursor pagination over a query that
-  ends in `.paginate(...)` on the server.
+The server query takes `paginationOpts` and returns `.paginate(...)` (see
+`lunora-functions`). The hook supplies the cursor:
+
+```tsx
+const { results, status, loadMore, error } = usePaginatedQuery(api.messages.page, { channelId }, { initialNumItems: 20 });
+// status: "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted"
+```
+
+Pages are live ranges: inserts and deletes inside a loaded page grow or shrink
+it in place without duplicating rows. There is no total count; subscribe to a
+separate count query for "42 of 1,203". `useInfiniteQuery` is the
+TanStack-style alternative.
+
 - `useConnectionStatus` — live socket state for an offline/reconnecting banner.
-- `usePresence` — who's-here + heartbeat (pairs with the `presence` registry
+- `usePresence` — who's-here with heartbeat (pairs with the `presence` registry
   item).
-- `useAuth` + the `Authenticated` / `Unauthenticated` / `AuthLoading` gates —
-  see `lunora-setup-auth`.
+- `useAuth` + `Authenticated` / `Unauthenticated` / `AuthLoading` — see
+  `lunora-setup-auth`.
+
+## Live Topics
+
+For an event with no query behind it ("a comment was posted"), the server
+publishes to a declared topic and the browser follows topics over one shared SSE
+connection (shared when the connection options match). Declare the stream and its
+topics once (`defineLiveStream({ id, topics: { post: { key: { postId: v.id("posts") },
+payload: v.object({...}) } }, onSubscribe })`), mount its two handlers on the HTTP
+router, and follow topics with the adapter's hook (all return `{ lastEvent, error }`).
+`onSubscribe` receives the parsed `{ ctx, topic, key, raw }`; do not split a string.
+A subscribe for an undeclared name, wrong arity or a non-canonical spelling is denied
+before `onSubscribe` runs. Codegen writes `_generated/live.ts`:
+
+| Package                | Primitive                 |
+| ---------------------- | ------------------------- |
+| `@lunora/react`, `vue` | `useLiveTopic`            |
+| `@lunora/solid`        | `createLiveTopic`         |
+| `@lunora/svelte`       | `liveTopic` (a store)     |
+| `@lunora/angular`      | `liveTopic` (signals)     |
+| `@lunora/react-native` | re-exports `useLiveTopic` |
+
+```tsx
+import { live } from "../lunora/_generated/live";
+
+// the route comes from the client in <LunoraProvider>; lastEvent / onEvent are typed by the payload
+const { lastEvent, error } = useLiveTopic(live.posts.post({ postId }), { onEvent: (payload) => refresh(payload) });
+```
+
+Svelte's `liveTopic` and Angular's `liveTopic` read the client when called: call
+them during component init (Angular: or pass `client` and `destroyRef`). Pass
+`shardKey` in the options to follow a `.shardBy` shard.
+
+- Several hooks with the same URL, credentials, headers, `retryDelay`, `maxDelayMs` and
+  `sessionKey` share a single connection; the last to unmount closes it. On a
+  cookie-authenticated stream pass `sessionKey` (the user id), or the connection
+  outlives a sign-out and keeps the previous user's topics.
+- Publish from server code with `ctx.live.publish(live.posts.post({ postId }), payload)`:
+  the ref names the stream, the payload is typed, and the shard refuses a payload the
+  topic's validator rejects (`BAD_REQUEST`). Topic names and key fields are plain
+  identifiers, key validators are string-valued, and a topic named `room` is refused.
+  `ctx.live` exists only on actions, HTTP actions, queue consumers and scheduled
+  actions, NOT on a query or mutation. It is always present on an HTTP action
+  but typed optional on an `action` and a queue consumer, so write
+  `ctx.live?.publish(...)` there. To tell a page about a write, have the
+  mutation `ctx.scheduler.runAfter(0, internal.x.publish, args)`: it is held until
+  the commit, so a rolled-back write sends nothing. If the page already has a
+  `useQuery` over those rows, skip the event.
+- Without `onSubscribe` every subscribe is DENIED (unless `allowAnonymousControl`
+  admits anonymous callers). Only a literal `true` allows.
+- Delivery is at least once (a retried action publishes again) and shard-local
+  (no fan-out across Durable Objects). Put an id in the payload to dedupe.
+- React Native's stock `fetch` does not stream, so events never arrive; use a
+  streaming `fetch` such as `expo/fetch`.
+- Live streams are native on Cloudflare and celld, emulated on Node. Codegen
+  refuses an app that reads `ctx.live` on a target that withholds them.
 
 ## `@lunora/db` — TanStack DB Collections
 
-For richer client state (indexed local collections, cross-query joins, a durable
-offline-transactions outbox), use `@lunora/db` instead of raw hooks. Scaffold
-with `vis generate lunora-collections` (wires `defineCollections` from your
-schema + functions into live TanStack DB collections). Reach for it when the app
-needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery`
-/`useMutation` are enough for straightforward live lists.
-
-## Common Pitfalls
-
-1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
-   render — create it once at module scope.
-2. **Treating `undefined` as empty.** `undefined` is "loading", `[]` is "loaded,
-   empty" — branch on both.
-3. **Broad query args.** A subscription keyed too broadly re-renders on
-   unrelated writes; scope `args` to what the component shows.
-4. **Optimistic shape drift.** The provisional value must match the query's
-   element shape (including `_id`/`_creationTime`) or the UI flickers when the
-   real delta lands.
+For indexed local collections, cross-query joins, or a durable offline outbox,
+use `@lunora/db` (peer deps `@tanstack/db`, `@tanstack/offline-transactions`).
+Plain `useQuery` / `useMutation` are enough for straightforward live lists.
+
+```ts
+import { defineCollections } from "@lunora/db";
+import type { LunoraClient } from "lunorash/client";
+
+import { api } from "../lunora/_generated/api";
+import type { Doc, Id } from "../lunora/_generated/dataModel";
+
+export const createCollections = (client: LunoraClient) =>
+    defineCollections(client, {
+        messages: {
+            list: api.messages.list,
+            scopeBy: "channelId", // the .shardBy column
+            insert: {
+                mutation: api.messages.send,
+                optimistic: (input: Omit<Doc<"messages">, "_id" | "_creationTime">, id) => ({ _id: id as Id<"messages">, _creationTime: Date.now(), ...input }),
+                toArgs: (row) => ({ channelId: row.channelId, id: row._id, text: row.text }),
+            },
+        },
+    });
+// → db.collections.* (feed useLiveQuery), db.actions.* (optimistic writes),
+//   db.scope.* (re-point sharded collections), db.executor (the outbox)
+```
+
+Call `defineCollections` once and treat its collections as the single source of
+truth per table. Optimistic writes and sync deltas land only on that instance,
+so a second instance or a copy of the rows in your own store drifts: derived
+indexes (trees, search, undo captures) built from the copy miss new rows and
+hold stale ones, while `useLiveQuery` still looks correct.
 
 ## Checklist
 
-- [ ] `LunoraClient` created once at module scope; app wrapped in the provider.
-- [ ] Live reads use `useQuery`; `undefined` handled as loading.
-- [ ] Writes use `useMutation`; `pending` disables submit; `optimistic` matches
-      the row shape.
-- [ ] Query `args` scoped narrowly to avoid over-broad re-renders.
-- [ ] Pagination via `usePaginatedQuery`/`useInfiniteQuery` over `.paginate`.
-- [ ] Considered `@lunora/db` if the app needs local indexes/joins or an outbox.
+- [ ] `LunoraClient` created once at module scope and registered the way the
+      adapter expects.
+- [ ] `undefined` handled as loading; `"skip"` used while args are incomplete;
+      `onError` wired where a failure must be visible.
+- [ ] Reads and writes on `.shardBy` tables pass `shardKey`.
+- [ ] Mutations destructure `mutate`; `pending` disables submit;
+      `optimisticUpdate` rows match the query's element shape.
+- [ ] Lists that grow use `usePaginatedQuery` over a `.paginate` query.
+- [ ] `@lunora/db`: one `defineCollections` instance; no parallel copy of rows.
+- [ ] Events that are not rows use a live topic, published from an action (via
+      `ctx.scheduler` after a write); data a query could return stays a `useQuery`.