rsc-universal 0.1.1

package/skills/react/references/data-and-state.md

@@ -0,0 +1,152 @@
+# Data & state — TanStack Query v5 + client state
+
+The SPA rule: **server data lives in the TanStack Query cache, client data lives in `useState`/store/URL.** Never put fetched data in `useState` synced by `useEffect`.
+
+## Query-key factory
+
+Keep keys consistent so invalidation hits exactly what you mean. A small factory beats stringly-typed keys scattered across files.
+
+```ts
+export const userKeys = {
+  all: ["users"] as const,
+  list: (filters: UserFilters) => [...userKeys.all, "list", filters] as const,
+  detail: (id: string) => [...userKeys.all, "detail", id] as const,
+};
+```
+
+## useQuery
+
+```tsx
+const { data, isPending, isError, error, refetch } = useQuery({
+  queryKey: userKeys.list(filters),
+  queryFn: () => api.listUsers(filters),
+  staleTime: 60_000,        // fresh for 1 min → no refetch on remount/focus within window
+  gcTime: 5 * 60_000,        // unused cache evicted after 5 min
+  placeholderData: (prev) => prev, // keep prior page visible while the next loads (pagination)
+});
+```
+
+- `staleTime` is the single biggest lever against over-fetching. Default `0` means refetch on every mount/focus.
+- Render states explicitly: `isPending` (no data yet) → spinner; `isError` → message + retry; else data.
+
+## Mutations: invalidate vs setQueryData
+
+```tsx
+const qc = useQueryClient();
+
+// Simplest correct pattern: invalidate, let the query refetch the truth.
+const create = useMutation({
+  mutationFn: api.createUser,
+  onSuccess: () => qc.invalidateQueries({ queryKey: userKeys.all }),
+});
+
+// When you already have the server's response, write it directly (one less round-trip).
+const update = useMutation({
+  mutationFn: api.updateUser,
+  onSuccess: (saved) => qc.setQueryData(userKeys.detail(saved.id), saved),
+});
+```
+
+Rule of thumb: **invalidate** when the server is the source of truth and a refetch is cheap; **`setQueryData`** when the mutation already returns the canonical object.
+
+## Optimistic update (delete with rollback)
+
+```tsx
+const remove = useMutation({
+  mutationFn: api.deleteUser,
+  onMutate: async (id: string) => {
+    await qc.cancelQueries({ queryKey: userKeys.all });      // stop in-flight refetches
+    const prev = qc.getQueryData<User[]>(userKeys.list(filters));
+    qc.setQueryData<User[]>(userKeys.list(filters),
+      (old) => old?.filter((u) => u.id !== id) ?? []);        // optimistic write
+    return { prev };                                           // context for rollback
+  },
+  onError: (_e, _id, ctx) => {
+    if (ctx?.prev) qc.setQueryData(userKeys.list(filters), ctx.prev); // rollback
+  },
+  onSettled: () => qc.invalidateQueries({ queryKey: userKeys.all }),  // reconcile with server
+});
+```
+
+The trio is non-negotiable: `onMutate` (snapshot + write), `onError` (restore the snapshot), `onSettled` (refetch the truth).
+
+## useSuspenseQuery + boundaries
+
+Move loading/error out of the component body.
+
+```tsx
+function Users() {
+  const { data } = useSuspenseQuery({ queryKey: userKeys.all, queryFn: api.listUsers });
+  return <List items={data} />; // data is never undefined here
+}
+
+<ErrorBoundary fallback={<Failed />}>
+  <Suspense fallback={<Skeleton />}>
+    <Users />
+  </Suspense>
+</ErrorBoundary>
+```
+
+This is also the correct promise source for a bare `use()` call — the cache owns a stable promise, so render doesn't loop.
+
+## Infinite & prefetch
+
+```tsx
+const q = useInfiniteQuery({
+  queryKey: userKeys.all,
+  queryFn: ({ pageParam }) => api.listUsers({ cursor: pageParam }),
+  initialPageParam: null,
+  getNextPageParam: (last) => last.nextCursor ?? undefined,
+});
+
+// Warm the cache before navigation (e.g. on hover):
+await qc.prefetchQuery({ queryKey: userKeys.detail(id), queryFn: () => api.getUser(id) });
+```
+
+## Client state — Zustand with narrow selectors
+
+```ts
+const useCart = create<CartState>((set) => ({
+  items: [],
+  add: (item) => set((s) => ({ items: [...s.items, item] })),
+}));
+
+// Bad: subscribes to the whole store → re-renders on any change
+const store = useCart();
+// Good: subscribe to one slice → re-renders only when count changes
+const count = useCart((s) => s.items.length);
+```
+
+## Context — wide reads, low write frequency
+
+```tsx
+const ThemeContext = createContext<Theme>("light");
+// React 19: the context value IS the provider
+<ThemeContext value={theme}>{children}</ThemeContext>
+```
+
+Do not put rapidly-changing values (mouse position, form keystrokes) in context — every consumer re-renders. Use a store with selectors instead.
+
+## Bad → Good catalog
+
+```tsx
+// Bad: derived state mirrored into useState + effect
+const [total, setTotal] = useState(0);
+useEffect(() => setTotal(items.reduce((s, i) => s + i.price, 0)), [items]);
+// Good
+const total = items.reduce((s, i) => s + i.price, 0);
+```
+
+```tsx
+// Bad: fetch on mount with effect (race + no cache + Strict-Mode double-fire)
+useEffect(() => { fetch(url).then(r => r.json()).then(setData); }, [url]);
+// Good
+const { data } = useQuery({ queryKey: [url], queryFn: () => fetch(url).then(r => r.json()) });
+```
+
+```tsx
+// Bad: resetting child state on prop change with an effect
+useEffect(() => setDraft(initial), [initial]);
+// Good: remount the subtree with a key
+<Editor key={initial.id} initial={initial} />
+```

package/skills/react/references/performance.md

@@ -0,0 +1,75 @@
+# Performance — measure, then fix the real bottleneck
+
+Never optimize from a hunch. Profile, find the component that actually re-renders or the chunk that's actually heavy, fix that.
+
+## 1. Profile first
+
+- **React DevTools Profiler**: record an interaction, read the flamegraph. "Why did this render?" (Profiler settings) names the prop/state/context that triggered each render.
+- Bundle size: `npx vite-bundle-visualizer` or `rollup-plugin-visualizer` to see what's actually shipped.
+- Field metrics: LCP < 2.5s, INP < 200ms, CLS < 0.1. Generic CWV measurement detached from React → `../performance/SKILL.md`.
+
+## 2. `key` correctness (the silent state bug)
+
+Index keys are fine for static lists. The moment a list can **reorder, insert, or delete**, an index key makes React reuse the wrong DOM/state — inputs keep old values, the wrong row animates, checkboxes stick to the wrong item.
+
+```tsx
+// Bad: index key on a mutable list → wrong row state after delete/reorder
+{users.map((u, i) => <Row key={i} user={u} />)}
+// Good: stable identity
+{users.map((u) => <Row key={u.id} user={u} />)}
+```
+
+## 3. Virtualize long lists
+
+Past ~50–100 rows the DOM node count, not React, is the cost. Render only the visible window.
+
+```tsx
+import { useVirtualizer } from "@tanstack/react-virtual";
+
+const v = useVirtualizer({
+  count: rows.length,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 48,
+  overscan: 8,
+});
+// render only v.getVirtualItems(), positioned by item.start
+```
+
+## 4. Code-split
+
+```tsx
+const Chart = lazy(() => import("./Chart")); // separate chunk, loaded on demand
+<Suspense fallback={<Spinner />}><Chart data={data} /></Suspense>
+```
+
+Vite emits a separate chunk for every dynamic `import()`. Split at route boundaries first, then heavy leaf components (charts, editors, maps).
+
+## 5. React Compiler vs manual memo
+
+When the **React Compiler** is enabled (Vite plugin / `babel-plugin-react-compiler`), it auto-memoizes components and values — **delete** manual `useMemo`/`useCallback`/`React.memo`; they're dead weight and noise.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [react({ babel: { plugins: ["babel-plugin-react-compiler"] } })],
+});
+```
+
+If the compiler is **not** on, memoize only what the Profiler proved expensive — not everything.
+
+## 6. Narrow store selectors → re-render map
+
+A component re-renders when a value it *subscribes to* changes. With Zustand, subscribe to the smallest slice:
+
+```ts
+// Bad: re-renders on any store change
+const { count } = useCart();
+// Good: re-renders only when the count changes
+const count = useCart((s) => s.items.length);
+```
+
+Same principle for context: a high-write context re-renders every consumer, so high-frequency values belong in a store with selectors, not context.
+
+## 7. Suspense for perceived speed
+
+Wrap independent data regions in their own `<Suspense>` so each reveals as its query resolves instead of blocking the whole screen on the slowest fetch. Pair `useSuspenseQuery` (see `data-and-state.md`) with per-region boundaries.

package/skills/react/references/routing.md

@@ -0,0 +1,99 @@
+# Client-side routing — React Router v7 (library mode) & TanStack Router
+
+SPA routing only. If you see `@react-router/dev` (React Router **framework mode**, the Remix successor with SSR), that is out of scope — treat it like `../nextjs/SKILL.md`-shape work.
+
+## React Router v7 — library mode
+
+```tsx
+import { createBrowserRouter, RouterProvider } from "react-router";
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    element: <RootLayout />,        // renders <Outlet/> for children
+    errorElement: <RouteError />,
+    children: [
+      { index: true, element: <Home /> },
+      { path: "users", lazy: () => import("./routes/users") },        // code-split chunk
+      { path: "users/:id", lazy: () => import("./routes/user-detail") },
+      { path: "*", element: <NotFound /> },
+    ],
+  },
+]);
+
+export function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+- **Nested routes** share a layout via `<Outlet/>`; each child is its own URL segment.
+- **`lazy`** makes each route a separate bundle chunk — the single biggest SPA bundle win.
+- **`errorElement`** catches thrown errors / loader rejections for that subtree.
+
+### Client loaders
+
+A `lazy` route module can export a `loader` to fetch before render. In an SPA, prefer driving loaders through the TanStack Query client so the data stays in one cache:
+
+```ts
+// routes/user-detail.tsx
+export async function loader({ params }: { params: { id: string } }) {
+  return queryClient.ensureQueryData({
+    queryKey: ["users", "detail", params.id],
+    queryFn: () => api.getUser(params.id),
+  });
+}
+export function Component() {
+  const { id } = useParams();
+  const { data } = useSuspenseQuery({ queryKey: ["users", "detail", id!], queryFn: () => api.getUser(id!) });
+  return <Profile user={data} />;
+}
+```
+
+### Protected route wrapper
+
+```tsx
+function RequireAuth({ children }: { children: React.ReactNode }) {
+  const user = useAuth();
+  const loc = useLocation();
+  if (!user) return <Navigate to="/login" replace state={{ from: loc }} />;
+  return children;
+}
+// { path: "settings", element: <RequireAuth><Settings/></RequireAuth> }
+```
+
+### Search params ARE state
+
+Filters, tabs, pagination belong in the URL so they're shareable and survive reload. Do not duplicate them into `useState`.
+
+```tsx
+const [params, setParams] = useSearchParams();
+const page = Number(params.get("page") ?? "1");
+const setPage = (p: number) =>
+  setParams((prev) => { prev.set("page", String(p)); return prev; });
+```
+
+## TanStack Router — the type-safe alternative
+
+Pick it when route params and search-param schemas must be fully typed end-to-end.
+
+```tsx
+const route = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/users/$userId",
+  validateSearch: (s) => userSearchSchema.parse(s), // typed, validated search params
+  loader: ({ params }) => queryClient.ensureQueryData(userQuery(params.userId)),
+  component: UserDetail,
+});
+// useParams() / useSearch() are fully typed from the route tree
+```
+
+- Type-safe `Link`, `useParams`, `useSearch` derived from the route tree.
+- First-class loaders and built-in integration with the TanStack Query cache.
+
+## Choosing
+
+| Need                                         | Use                          |
+| -------------------------------------------- | ---------------------------- |
+| Familiar API, large ecosystem                | React Router v7 library mode |
+| Fully typed params + validated search params | TanStack Router              |
+| SSR / streaming / server actions             | not here → `../nextjs/SKILL.md` |

package/skills/react/scripts/verify.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# verify.sh — React + Vite SPA project gate.
+#
+# Usage:
+#   bash scripts/verify.sh            # run from the Vite project root
+#
+# What it does (in order): ESLint -> tsc --noEmit -> Vitest -> vite build.
+# Each tool is detected; if it is not installed/resolvable (or its config/tests
+# are absent) it is SKIPPED with a yellow warning, NEVER a failure. A repo that
+# does not have a tool cannot fail a command it does not own. Exits non-zero
+# only on a real tool failure; exits 0 on a clean or empty target.
+#
+# Side effects: the lint / type-check / test steps are read-only. The final
+# `vite build` WRITES the `dist/` output directory — it is not a pure read-only
+# step. No installs, no network mutations. Safe to re-run.
+#
+# Portability: targets stock macOS bash 3.2. No `mapfile`; no empty-array
+# expansion under `set -u`. `set -e` is intentionally NOT used (each check owns
+# its exit code); `set -u` is on.
+
+set -u
+
+# --- colors (only when stdout is a TTY) -----------------------------------
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+skips=""  # space-separated (bash 3.2 safe under set -u)
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; skips="${skips}${skips:+ }$2"; return 0; }
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- guard: only meaningful inside a Node/Vite project --------------------
+if [ ! -f package.json ]; then
+  printf '%s\n' "${YELLOW}no package.json here — nothing to verify${RESET}"
+  exit 0
+fi
+
+# --- resolve a package runner from the lockfile ----------------------------
+RUN=""
+if [ -f pnpm-lock.yaml ] && have pnpm; then
+  RUN="pnpm exec"
+elif [ -f yarn.lock ] && have yarn; then
+  RUN="yarn"
+elif [ -f package-lock.json ] && have npm; then
+  RUN="npm exec --"
+elif have npx; then
+  RUN="npx --no-install"
+fi
+
+run_bin() {
+  # run_bin <bin-name> <args...> : true if the bin is resolvable and runs
+  bin="$1"; shift
+  if have "$bin"; then "$bin" "$@"; return $?; fi
+  if [ -x "node_modules/.bin/$bin" ]; then "node_modules/.bin/$bin" "$@"; return $?; fi
+  if [ -n "$RUN" ]; then $RUN "$bin" "$@"; return $?; fi
+  return 127
+}
+
+bin_available() {
+  bin="$1"
+  have "$bin" && return 0
+  [ -x "node_modules/.bin/$bin" ] && return 0
+  return 1
+}
+
+# --- 1. ESLint -------------------------------------------------------------
+if bin_available eslint; then
+  printf '%s\n' "Running ESLint..."
+  if run_bin eslint .; then ok "eslint"; else fail "eslint"; fi
+else
+  warn "eslint not resolvable — skipping lint" "eslint"
+fi
+
+# --- 2. TypeScript ---------------------------------------------------------
+if bin_available tsc && [ -f tsconfig.json ]; then
+  printf '%s\n' "Running tsc --noEmit..."
+  if run_bin tsc --noEmit; then ok "tsc --noEmit"; else fail "tsc --noEmit"; fi
+else
+  warn "tsc or tsconfig.json missing — skipping type check" "tsc"
+fi
+
+# --- 3. Vitest -------------------------------------------------------------
+# Treat the repo as having Vitest unit tests when a vitest config exists OR
+# *.test.* files exist. Playwright e2e uses *.spec.* and must not trigger Vitest.
+has_tests=false
+if ls vitest.config.* vitest.workspace.* >/dev/null 2>&1; then
+  has_tests=true
+elif find . \( -name node_modules -o -name dist -o -name .git \) -prune -o \
+       -name '*.test.*' -print 2>/dev/null | grep -q .; then
+  has_tests=true
+fi
+if bin_available vitest && [ "$has_tests" = true ]; then
+  printf '%s\n' "Running vitest run..."
+  if run_bin vitest run; then ok "vitest"; else fail "vitest"; fi
+else
+  warn "vitest or unit tests (vitest.config.* / *.test.*) not present — skipping unit tests" "vitest"
+fi
+
+# --- 4. vite build (slow; WRITES dist/; run last) --------------------------
+if bin_available vite; then
+  printf '%s\n' "Running vite build... (writes dist/)"
+  if run_bin vite build; then ok "vite build"; else fail "vite build"; fi
+else
+  warn "vite not resolvable — skipping build" "vite build"
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\n'
+if [ -n "$skips" ]; then
+  printf '%s\n' "${YELLOW}skipped: ${skips}${RESET}"
+fi
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}verify.sh: $failures check(s) failed${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+exit 0

package/skills/react-native/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: react-native
+description: "Use when writing the JS/TS code inside a React Native or Expo app — screens, navigation, lists, animation, platform-conditional UI, data/offline state, and native-module authoring — and when killing runtime jank or render bugs. Triggers: 'scaffold an Expo Router app', 'FlashList vs FlatList', 'auth-gated route groups', 'gesture reattaches every render', 're-render storm on every keystroke', 'deep link lands on the wrong screen', 'write an Expo Module wrapping a native SDK', 'la llista pateix lag quan faig scroll', 'mi app va fluida en iOS pero a tirones en Android'. NOT eas build/submit/OTA update/prebuild/config-plugin (that is expo), NOT a Dart app (that is flutter), NOT web React/DOM (that is react or nextjs)."
+tags: [react-native, expo, mobile, ios, android, navigation, performance]
+recommends: [expo, react, flutter, design, debug, performance]
+origin: risco
+---
+
+# React Native (app code)
+
+You write the code that runs *inside* the app: render, navigate, animate, list, persist, and author native modules. The pipeline around it — building, signing, OTA, native config — is not yours.
+
+## What this skill owns
+
+Mobile is split across two skills by **verb**. Run the verb test before doing anything:
+
+| Verb in the request | Skill |
+|---|---|
+| render / navigate / animate / list / persist / author-native-module / debug-runtime | **react-native** (here) |
+| build / submit / update (OTA) / prebuild / config-plugin / `eas.json` / channel / runtime-version | **`../expo/SKILL.md`** |
+
+Assume the **New Architecture is on** (Fabric + Turbo Modules). It is mandatory from RN 0.82 / Expo SDK 55 — RN 0.82 (2025-10-08) ignores any disable flag, and SDK 55 is New-Arch-only. SDK 54 (RN 0.81) was the last that could opt out. Never write `newArchEnabled: false` to dodge a bug; fix the bug. Why: the flag is a no-op on current versions, so the "fix" silently does nothing.
+
+Reference SDK→RN map (accessed 2026-06-02): **SDK 53** = RN 0.79, **SDK 54** = RN 0.81 (React Compiler GA), **SDK 55** = RN 0.83.
+
+## Project shape — pick a router first
+
+This is the one real branch at scaffold time:
+
+| Use | When |
+|---|---|
+| **Expo Router** (file-based) | New apps, web parity, deep links, typed routes. The recommended default. It is a layer on top of React Navigation; both are Expo-team maintained. |
+| **React Navigation v7** (static API) | Brownfield apps, native integration, highly bespoke custom transitions where you need imperative control. |
+
+Default file tree for an Expo Router app:
+
+```text
+app/                  # routes — file system IS the navigation
+  (auth)/             # group: unauthenticated screens
+  (app)/              # group: authenticated screens
+    (tabs)/           # nested tab navigator
+  _layout.tsx         # root layout + providers
+components/           # dumb, reusable UI
+features/<domain>/    # feature-scoped screens, hooks, components
+lib/                  # clients, query setup, storage, utils
+```
+
+Keep route files thin: a route file wires params and renders a feature component. Put logic in `features/`. Why: routes get re-mounted by navigation; business logic in them is hard to test and re-runs unexpectedly.
+
+## Navigation
+
+Type your routes. With Expo Router, enable typed routes and let `useLocalSearchParams<{ id: string }>()` carry the contract. Why: deep links and back-stack restoration pass strings you will otherwise misread.
+
+Gate auth at the **group layout**, declaratively — not imperatively inside an effect:
+
+```tsx
+// app/(app)/_layout.tsx — Bad: imperative nav in an effect races the first paint
+export default function AppLayout() {
+  const { user } = useAuth();
+  useEffect(() => {
+    if (!user) router.replace('/(auth)/sign-in'); // flashes protected UI first
+  }, [user]);
+  return <Stack />;
+}
+```
+
+```tsx
+// app/(app)/_layout.tsx — Good: redirect before children mount
+import { Redirect, Stack } from 'expo-router';
+export default function AppLayout() {
+  const { user, loading } = useAuth();
+  if (loading) return null;          // or a splash
+  if (!user) return <Redirect href="/(auth)/sign-in" />;
+  return <Stack />;
+}
+```
+
+Modals/sheets: declare presentation on the screen, not by pushing a styled full-screen route — `<Stack.Screen options={{ presentation: 'modal' }} />`. Configure deep links via the `scheme` + the linking config so a cold-start link resolves to the right nested route, not just the root. A deep link landing on the wrong screen is almost always a group/segment mismatch between the URL and the `app/` tree.
+
+## Lists & performance
+
+Switch from `FlatList` to **FlashList** (Shopify) once a list crosses **~100 items**, has variable row heights, or renders images. Why: FlashList recycles views instead of mounting one per row, so memory and scroll jank stay flat as the list grows.
+
+Three things every long list needs:
+
+1. A stable `keyExtractor` — return a real id, never the index. Index keys defeat recycling and reorder rows on insert.
+2. `getItemType` when rows differ structurally (header vs product vs ad). Why: it lets FlashList recycle within a type instead of remeasuring.
+3. A memoized row component with **no inline closures or style objects** in `renderItem`.
+
+```tsx
+// Bad: new fn + new style object every parent render -> every visible row re-renders
+<FlashList
+  data={items}
+  renderItem={({ item }) => (
+    <Pressable style={{ padding: 12 }} onPress={() => open(item.id)}>
+      <Text>{item.title}</Text>
+    </Pressable>
+  )}
+/>
+```
+
+```tsx
+// Good: stable refs, memoized row, typed rows
+const Row = memo(function Row({ item }: { item: Product }) {
+  const open = useOpenProduct();          // stable from context/store
+  return (
+    <Pressable style={styles.row} onPress={() => open(item.id)}>
+      <Text>{item.title}</Text>
+    </Pressable>
+  );
+});
+
+<FlashList
+  data={items}
+  keyExtractor={(it) => it.id}
+  getItemType={(it) => it.kind}
+  renderItem={({ item }) => <Row item={item} />}
+/>
+```
+
+FlashList caveat: rows can flash into the wrong position for a split second if mounted while entry animations run. Disable entry animations on the **initial** mount.
+
+React Compiler (GA in SDK 54) auto-memoizes components and reduces manual `useMemo`/`useCallback` — but it does **not** remove the need for virtualization, stable keys, or `getItemType`. Don't delete your list discipline because the compiler is on. For re-render hunting and profiling, see `references/performance-debugging.md`.
+
+## Animation & gestures
+
+Reanimated worklets run on the **UI thread**, so animations keep going at 60fps even when JS is busy. Reanimated 4 (stable Oct 2025) requires the New Architecture / RN 0.76+ and adds CSS-style animations while keeping the worklet API. Many teams stay on Reanimated 3 for dependency compatibility — match the project's installed major.
+
+Two rules that fix most gesture bugs:
+
+- Wrap gesture objects in `useMemo`. Why: a new gesture object each render reattaches the recognizer and drops in-flight touches.
+- Cross to JS only at the boundary with `runOnJS`. Why: calling a JS-thread function directly from a worklet crashes; everything inside the worklet must stay on the UI thread.
+
+```tsx
+// Good: memoized gesture, UI-thread shared value, JS only at the end
+const x = useSharedValue(0);
+const pan = useMemo(
+  () =>
+    Gesture.Pan()
+      .onUpdate((e) => { x.value = e.translationX; })            // UI thread
+      .onEnd(() => { runOnJS(onSwiped)(); x.value = withSpring(0); }), // boundary
+  [onSwiped],
+);
+```
+
+Use Reanimated 4 CSS animations for simple declarative cases (fades, simple transitions); use worklets for gesture-driven or physics-based motion. Never animate layout on the JS thread when a shared value will do it on the UI thread.
+
+## Platform-conditional code
+
+- Small forks: `Platform.select({ ios: 12, android: 8 })` or `Platform.OS === 'ios'`.
+- Whole-component forks: `Button.ios.tsx` / `Button.android.tsx` — the bundler picks the right one; import `./Button` with no extension.
+- Safe area: use `react-native-safe-area-context` insets, not hardcoded notch padding. Why: insets differ per device and orientation.
+- `KeyboardAvoidingView` behaves differently per platform — `padding` on iOS, often `height` or nothing on Android; test both, don't assume the iOS behavior ports.
+- Set the status bar style explicitly per screen via `expo-status-bar`.
+
+## Data & state
+
+- **Server state → TanStack Query.** It owns caching, dedupe, retries, and background refetch. Don't hand-roll loading flags in component state.
+- **Persistence:** **MMKV** for fast synchronous key/value (auth tokens, flags, small prefs); **expo-sqlite + Drizzle** for relational or offline-first data. Pick by shape, not habit.
+- Don't reach for Redux by default. Server state lives in Query; the small amount of true client state fits in context or Zustand.
+- Offline-first: persist the Query cache and treat the network as an enhancement, not a precondition.
+
+## Native modules — pick the path
+
+| Path | When | Cost |
+|---|---|---|
+| **Plain JS wrapper** of an existing lib | A maintained npm package already bridges the native API | None — do this first |
+| **Expo Modules API** (Swift/Kotlin) | App uses Expo; you want clean Swift/Kotlin, no codegen | Requires Expo; least boilerplate |
+| **Turbo Module** (codegen from TS specs) | Bare RN, or you need the RN-default path | Codegen specs + more boilerplate |
+| **Nitro Modules** | Hot path needing max throughput | Emerging; weigh maturity |
+
+Minimal Expo Module skeleton (definition lives in the module's Swift/Kotlin):
+
+```swift
+// ios/MyModule.swift
+import ExpoModulesCore
+public class MyModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("MyModule")
+    Function("hello") { (name: String) -> String in "Hi \(name)" }
+  }
+}
+```
+
+```ts
+// index.ts — typed JS surface
+import { requireNativeModule } from 'expo-modules-core';
+const MyModule = requireNativeModule('MyModule');
+export function hello(name: string): string { return MyModule.hello(name); }
+```
+
+Full Expo Module (Swift + Kotlin + view), the Turbo Module codegen-spec walkthrough, packaging, and autolinking → `references/native-modules.md`.
+
+## Debugging
+
+- Read **Hermes** stack traces from the bottom up; the JS frame that matters is usually above the native bridge frames.
+- "Works on iOS, breaks on Android" (or vice versa) → run the platform-divergence checklist in `references/performance-debugging.md` before guessing.
+- A red screen citing the interop layer is usually an old-architecture lib running under Fabric — update the lib or find a New-Arch-ready replacement; do **not** disable New Arch.
+
+## Anti-patterns
+
+| Anti-pattern | Why it hurts | Do instead |
+|---|---|---|
+| `FlatList` for 5k rows / image feeds | Mounts a view per row; jank + memory blowup | FlashList with `getItemType` + stable `keyExtractor` |
+| Inline arrow / style object in `renderItem` | New ref every render re-renders every visible row | Memoized `Row`, `StyleSheet.create`, stable handlers |
+| Gesture object built inline each render | Reattaches recognizer, drops in-flight touches | Wrap in `useMemo` keyed on real deps |
+| `setState` in render path | Render loop / re-render storm on every keystroke | Derive in render or move to an event handler |
+| Imperative `router.replace` in an effect to gate auth | Flashes protected UI, races first paint | `<Redirect>` at the group layout |
+| `newArchEnabled: false` to dodge a New-Arch bug | No-op on RN 0.82+/SDK 55; hides the real cause | Update the offending lib; fix the bug |
+| Animating layout on the JS thread | Drops frames when JS is busy | Reanimated shared value on the UI thread |
+| Index as list key | Breaks recycling, reorders rows on insert | Stable domain id |
+| Doing native config / `eas.json` / OTA here | Wrong skill; this is app code | `../expo/SKILL.md` |
+| Hardcoded notch/safe-area padding | Wrong on other devices/orientations | `react-native-safe-area-context` insets |
+
+## Cross-references
+
+- Building, signing, OTA, native config → `../expo/SKILL.md`
+- Dart cross-platform alternative → `../flutter/SKILL.md`
+- Layout/visual design decisions → `../design/SKILL.md`
+- Systematic runtime fault isolation → `../debug/SKILL.md`

package/skills/react-native/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — react-native
+
+These cases are prompt-routing fixtures, not executable tests. `should_trigger` lists prompts that must select `react-native`; `should_not_trigger` lists prompts that must route to the named sibling instead (`expo`, `flutter`, `nextjs`, `ship`); `capability` describes a realistic scenario plus a `must_include` rubric the generated answer should cover. Run them through the repo's eval harness, which checks selection on each trigger prompt, correct sibling routing on each non-trigger, and that every rubric item is addressed by the model's answer to the capability scenario. There is nothing to install; judge by reading the cases against the harness output.