@damiangilgonzalez/harness 1.3.7

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,215 @@
+---
+name: react-native
+description: "Use when writing the JS/TS inside a React Native or Expo app — screens, Expo Router navigation, lists, Reanimated gestures, platform forks, offline state, native modules — or killing jank and render storms. NOT eas build/submit/OTA/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, performance]
+origin: risco
+---
+
+# React Native (app code)
+
+**Hand-off — the app vs its motion.** Animation and gestures in a React Native app — Reanimated
+worklets on the UI runtime, gesture handoff, sheets, press feedback, haptics — are
+`../motion-craft/SKILL.md`'s, whose guidance is platform-agnostic and applies to bare React Native as well as Expo.
+
+
+You write the code that runs *inside* the app: render, navigate, animate, list, persist, and author native modules. 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. Palette, type scale and layout intent are not decided here → `../design/SKILL.md`.
+- `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.
+- A fault that resists all of the above needs systematic isolation, not more guesses → `../debug/SKILL.md`.
+
+## 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 |

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.

package/skills/react-native/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: react-native
+
+should_trigger:
+  - prompt: "Scaffold an Expo Router app with auth-gated tabs and typed routes."
+    why: "Project shape + navigation gating is the core app-code surface this skill owns."
+  - prompt: "My product list re-renders every visible row on each keystroke in the search box — how do I stop it?"
+    why: "Non-obvious render-storm symptom; the fix (memoized rows, debounced query, virtualization) lives here, not in expo."
+  - prompt: "Write a native module wrapping the iOS HealthKit / Android Health Connect SDK for my Expo app."
+    why: "Native-module authoring (Expo Modules API vs Turbo Module) is explicitly this skill's territory."
+  - prompt: "La llista de productes pateix lag quan faig scroll en una FlatList de 5000 items."
+    why: "Catalan list-jank phrasing; FlashList migration + getItemType is the answer this skill gives."
+  - prompt: "Deep link opens the app but lands on the wrong screen instead of the nested tab."
+    why: "Deep-link/group-segment mismatch is app-routing, owned here; not a build/OTA concern."
+  - prompt: "My swipe gesture drops mid-drag and the recognizer seems to reset on every render."
+    why: "Gesture-object-in-useMemo issue; UI-thread/worklet reasoning is this skill's animation section."
+
+should_not_trigger:
+  - prompt: "eas build fails with a provisioning profile error."
+    route_to: expo
+    why: "Build pipeline / signing is the expo half of the verb test, not app code."
+  - prompt: "Rebuild the same app in Flutter with the same screens."
+    route_to: flutter
+    why: "Dart/Flutter toolchain, different framework entirely."
+  - prompt: "My Next.js server component won't render the product list."
+    route_to: nextjs
+    why: "Web React / SSR, DOM primitives — not React Native."
+  - prompt: "Cut a 1.4.0 release and tag the CI pipeline for it."
+    route_to: none
+    why: Release orchestration / CI has no dedicated shipping skill in this catalog, not in-app code.
+  - prompt: "My OTA update isn't showing up on devices after publish."
+    route_to: expo
+    why: "OTA update channels/runtime-version belong to the expo pipeline."
+
+capability:
+  - scenario: "A long product feed janks while scrolling on Android (smooth on iOS). The team is on Expo SDK 54 and wants it back to 60fps."
+    must_include:
+      - "Profile re-renders first (React DevTools Profiler / why-did-you-render) rather than guessing."
+      - "Migrate FlatList to FlashList with getItemType for structurally different rows."
+      - "Memoized row component with a stable keyExtractor (domain id, not index) and no inline closures/styles in renderItem."
+      - "Move scroll-driven animation to a Reanimated worklet on the UI thread, or disable entry animations on initial mount to stop the position flash."
+      - "Confirm the New Architecture is on and that no dependency is forcing the legacy interop path; do not set newArchEnabled:false."
+      - "Note React Compiler (SDK 54) reduces manual memo but does not remove virtualization / list discipline."

package/skills/react-native/references/native-modules.md

@@ -0,0 +1,123 @@
+# Native modules — full walkthrough
+
+When a maintained npm package already bridges the native API, use it and stop. Author a module only when there is no maintained wrapper, you need an API the wrapper doesn't expose, or you're shipping the SDK yourself.
+
+## Decision recap
+
+- **Expo Modules API** — Swift/Kotlin, no codegen, ergonomic DSL. Requires the app to use Expo. Lowest boilerplate; the default for Expo apps.
+- **Turbo Module** — codegen from TypeScript/Flow spec files. The RN-default path; works in bare RN. More boilerplate, fully typed across the boundary.
+- **Nitro Modules** — emerging high-performance option for hot paths. Weigh maturity before betting a shipping feature on it.
+
+## Expo Modules API — full example
+
+A module that exposes a function, a constant, an event, and a native view.
+
+```swift
+// ios/HealthModule.swift
+import ExpoModulesCore
+
+public class HealthModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("HealthModule")
+
+    Constants(["isAvailable": HKHealthStore.isHealthDataAvailable()])
+
+    Events("onStepsUpdate")
+
+    AsyncFunction("readSteps") { (start: Double, end: Double) -> Int in
+      // query HealthKit, return a step count
+      return 0
+    }
+
+    View(HealthChartView.self) {
+      Prop("range") { (view: HealthChartView, range: String) in
+        view.setRange(range)
+      }
+    }
+  }
+}
+```
+
+```kotlin
+// android/src/main/java/com/app/HealthModule.kt
+package com.app
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class HealthModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("HealthModule")
+    Constants("isAvailable" to HealthConnectClient.isAvailable())
+    Events("onStepsUpdate")
+    AsyncFunction("readSteps") { start: Double, end: Double ->
+      // query Health Connect, return a step count
+      0
+    }
+    View(HealthChartView::class) {
+      Prop("range") { view: HealthChartView, range: String -> view.setRange(range) }
+    }
+  }
+}
+```
+
+```ts
+// src/HealthModule.ts — the typed JS surface
+import { requireNativeModule, requireNativeViewManager } from 'expo-modules-core';
+
+type HealthNative = {
+  isAvailable: boolean;
+  readSteps(start: number, end: number): Promise<number>;
+  addListener(event: 'onStepsUpdate', cb: (e: { steps: number }) => void): { remove(): void };
+};
+
+const Native = requireNativeModule<HealthNative>('HealthModule');
+
+export const isHealthAvailable = Native.isAvailable;
+export const readSteps = (start: Date, end: Date) =>
+  Native.readSteps(start.getTime(), end.getTime());
+export const HealthChartView = requireNativeViewManager('HealthModule');
+```
+
+Notes:
+- `AsyncFunction` returns a Promise to JS without blocking the UI thread; use `Function` only for cheap synchronous calls.
+- `Constants` are read once at module init — don't use them for values that change.
+- Events: emit from native with `sendEvent("onStepsUpdate", ...)`; JS subscribes via `addListener`.
+
+## Turbo Module — codegen spec walkthrough
+
+Turbo Modules generate native interfaces from a TS spec. The spec file name must start with `Native`.
+
+```ts
+// specs/NativeHealth.ts
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  readonly isAvailable: () => boolean;
+  readSteps(start: number, end: number): Promise<number>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Health');
+```
+
+Configure codegen in `package.json`, then `pod install` (iOS) / build (Android) runs codegen and emits the C++/ObjC++/Java interfaces you implement:
+
+```json
+{
+  "codegenConfig": {
+    "name": "RNHealthSpec",
+    "type": "modules",
+    "jsSrcsDir": "specs"
+  }
+}
+```
+
+You then implement the generated protocol in Objective-C++/Swift and the generated abstract class in Java/Kotlin. The contract is enforced at build time — a signature mismatch fails codegen rather than crashing at runtime.
+
+## Packaging & autolinking
+
+- Expo Modules in a library: ship an `expo-module.config.json` so autolinking discovers it; the host app needs no manual linking.
+- Turbo Module in a library: a `react-native.config.js` / podspec drives autolinking.
+- Test on a **real device** for anything touching sensors, permissions, or background work — simulators lie about HealthKit, Bluetooth, and camera.
+- Version-gate native APIs (HealthKit availability, Health Connect install state) before calling; expose the gate as a JS-readable constant so the UI can degrade gracefully.

package/skills/react-native/references/performance-debugging.md

@@ -0,0 +1,46 @@
+# Performance & debugging deep dive
+
+## Re-render profiling
+
+Before optimizing, measure. Don't guess which component re-renders.
+
+1. Open React DevTools Profiler, record, do the slow interaction (scroll, type), stop. Components that flash on every commit are your targets.
+2. Highlight updates / the Profiler's "why did this render" tells you whether props, state, or context changed.
+3. `why-did-you-render` (dev-only) logs the exact prop that changed reference. Useful for the classic "new object/array literal every render" leak.
+
+With React Compiler on (SDK 54+), most manual `useMemo`/`useCallback` are redundant — but the compiler can't memoize across a virtualized list boundary, so list-row discipline still matters.
+
+The keystroke re-render storm: a search box whose `onChangeText` calls `setState` at the screen root re-renders the whole list on each character. Fix by either (a) keeping the input state local to a memoized search component and debouncing the query, or (b) deriving filtered data with a stable selector so only the list body recommits.
+
+## FlashList tuning knobs
+
+- `getItemType` — return a discriminator (`'header' | 'product' | 'ad'`). Recycling happens within a type; mixing types without it forces remeasures.
+- `keyExtractor` — stable domain id, never index.
+- Disable entry/layout animations on the **initial** mount — rows can flash into the wrong position for a split second when mounted while animations run.
+- Keep `renderItem` pure: no inline closures, no inline style objects, memoized row component.
+- For images, use a caching image component and fixed dimensions so layout doesn't thrash during scroll.
+
+## Reanimated thread model
+
+- Worklets run on the **UI thread**; shared values mutate there without a JS round-trip, so motion survives a busy JS thread.
+- A worklet calling a plain JS function crashes — cross back only via `runOnJS(fn)(...args)`, and only at the boundary (gesture end, completion callback).
+- Build gesture objects in `useMemo`; a fresh object each render reattaches the recognizer and drops in-flight touches.
+- Reanimated 4 needs the New Architecture / RN 0.76+. Reanimated 4 CSS animations cover simple declarative motion; reserve worklets for gesture-driven or physics-based animation.
+
+## Hermes crash triage
+
+- Read Hermes stack traces bottom-up; the meaningful JS frame usually sits just above the native bridge frames.
+- Symbolicate release crashes against the matching source map — an un-symbolicated trace is just addresses.
+- A red screen citing the interop layer under Fabric almost always means an old-architecture dependency. Update it or replace it with a New-Arch-ready package. Do not set `newArchEnabled: false` — it is a no-op on RN 0.82+/SDK 55 and only hides the cause.
+
+## Platform-divergence checklist
+
+When something works on one platform and breaks on the other, walk this before guessing:
+
+1. Is there a `.ios.tsx`/`.android.tsx` fork or a `Platform.select` branch diverging behavior?
+2. `KeyboardAvoidingView` behavior prop — `padding` (iOS) vs `height`/none (Android)?
+3. Safe-area insets — hardcoded padding that only fits one device family?
+4. Permissions — declared in `Info.plist` (iOS) and `AndroidManifest.xml` (Android), requested at runtime on both?
+5. A native dependency that ships only one platform's implementation, or differs in New-Arch readiness?
+6. Shadow/elevation — `shadow*` (iOS) vs `elevation` (Android) styled separately?
+7. Default font, line height, and ripple/highlight feedback differ — is the divergence cosmetic and expected, or a real bug?