@lunora/cli 1.0.0-alpha.15 → 1.0.0-alpha.151

package/skills/lunora-realtime/SKILL.md

@@ -2,8 +2,8 @@
 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.
+    pagination, connection status, the React/Vue/Solid/Svelte/Angular/React Native
+    adapters, and the `@lunora/db` TanStack binding.
 ---
 
 # Lunora Realtime
@@ -15,7 +15,8 @@ automatic rollback.
 
 ## When to Use
 
-- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
+- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte, Angular,
+  React Native/Expo, or an Astro/Nuxt meta-framework).
 - Adding optimistic updates, pagination, or presence to the UI.
 - Choosing between live hooks and the `@lunora/db` collection layer.
 
@@ -42,6 +43,19 @@ const client = new LunoraClient({ url });
 Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
 `@lunora/svelte`; the hook names and semantics below mirror across them.
 
+Two adapters differ in shape:
+
+- **`@lunora/angular`** is signal-based rather than hook-based: register with
+  `provideLunora(...)`, read the client via `injectLunoraClient()`, and use
+  `liveQuery(...)` / `mutate(...)` / `connectionStatus(...)` in place of the
+  hooks below.
+- **`@lunora/react-native`** re-exports all of `@lunora/react` and adds
+  `createLunoraClient` (plus `@lunora/react-native/auth` for the better-auth
+  Expo bridge) — build the client with that instead of `new LunoraClient`.
+
+For SSR meta-frameworks, `@lunora/astro` and `@lunora/nuxt` compose Lunora into
+the server (Nitro for Nuxt) and ship reactive-loader server helpers.
+
 ## Live Queries
 
 `useQuery(reference, args)` opens a subscription and returns the value, or
@@ -67,33 +81,32 @@ const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
 
 ## 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:
-
-- 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.
-
-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.
+**Live queries are identity-aware.** At the WebSocket upgrade the runtime
+stamps the caller's verified identity onto the socket (from the server-minted
+`x-lunora-userid` / `x-lunora-identity` headers, which a client cannot forge).
+Every subscription re-run, shape resolution, and poke-driven refresh executes
+under that socket's own identity, passed by value so a concurrent RPC can't
+clobber it.
+
+Practically, this means:
+
+- `.use(rls(...))` and `ctx.auth.userId` work the same in a subscribed query as
+  in a one-shot read. Shape subscriptions AND-merge the shape predicate with
+  the table's RLS read base-where, so the membership query the poke protocol
+  runs is RLS-correct by construction — never the client's word for it.
+- An **anonymous** socket carries no identity, so an RLS/`ctx.auth` query fails
+  closed (empty/denied) rather than leaking another user's rows.
+- **Token expiry is enforced on the socket.** When the resolved credential
+  carries an expiry, the DO sends a `TOKEN_EXPIRED` error frame and closes with
+  code `4001` at the next send at or after that instant. `LunoraClient`
+  reconnects automatically and re-resolves a fresh identity — but surface it in
+  the UI if a re-login is required.
+
+You can still scope data structurally when it fits the domain — `.shardBy(userId)`
+(or tenant/room) partitions state so a subscription is narrow by construction,
+and explicit query args keep subscriptions cheap (see the args-scoping note
+above). Prefer those for _performance_; use `rls()` / `ctx.auth` for
+_authorization_. They compose.
 
 ## Mutations + Optimistic Updates
 
@@ -154,6 +167,13 @@ 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.
 
+Call `defineCollections` **once** at module scope and treat the returned
+collections as the single source of truth for each table. Don't mirror rows into
+a parallel store, and never build derived indexes (trees, search, undo captures)
+from a copy — optimistic writes and sync deltas land only on the Lunora
+collection, so code reading a copy silently reads stale rows while `useLiveQuery`
+renders fresh data.
+
 ## Common Pitfalls
 
 1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
@@ -165,6 +185,12 @@ needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery
 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.
+5. **Two sources of truth for the same rows.** `defineCollections` more than once
+   per table (or a parallel store of your own) mints copies that drift. Reads
+   through `useLiveQuery` look fine, but derived indexes built from the copy can
+   **miss rows** — rows written to the collection after the copy was taken never
+   appear in the index — or **hold stale rows** — rows updated or deleted in the
+   collection still show their old value. One instance, one collection per table.
 
 ## Checklist
 
@@ -175,3 +201,5 @@ needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery
 - [ ] 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.
+- [ ] `@lunora/db`: one `defineCollections` instance; no parallel copy of rows;
+      derived indexes built from the same collection the UI renders.