@rosetears/aili-pi 0.1.0

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

@@ -0,0 +1,215 @@
+# Performance Reference
+
+Diagnosing and fixing performance issues in React Native / Expo apps.
+
+## Profiling Workflow
+
+Before optimizing, identify the actual bottleneck:
+
+1. **JS thread** — Open React Native DevTools (press `j` in Metro terminal) → Profiler tab → record interaction → look for components with long render times
+2. **Native thread** — iOS: Xcode Instruments (Time Profiler); Android: Android Studio CPU Profiler
+3. **Measure, don't guess** — Always reproduce the issue in a release-like build (`npx expo run:ios --configuration Release`)
+
+## Rendering
+
+### Virtualized Lists
+
+Never render large datasets inside a `ScrollView`. Use a virtualized list that recycles off-screen views:
+
+```tsx
+import { FlashList } from "@shopify/flash-list";
+
+function ProductCatalog({ products }: { products: Product[] }) {
+  return (
+    <FlashList
+      data={products}
+      renderItem={({ item }) => <ProductRow product={item} />}
+      estimatedItemSize={72}
+      keyExtractor={(p) => p.sku}
+    />
+  );
+}
+
+const ProductRow = memo(function ProductRow({ product }: { product: Product }) {
+  return (
+    <View style={rowStyles.container}>
+      <Image source={product.thumbnail} style={rowStyles.image} />
+      <Text style={rowStyles.title}>{product.name}</Text>
+    </View>
+  );
+});
+```
+
+Key points:
+- Wrap list items with `memo` to skip re-renders when props haven't changed
+- Always provide `estimatedItemSize` — FlashList uses it for layout estimation
+- Extract `renderItem` or use a named component to keep stable references
+
+### Minimizing Re-renders
+
+**Split state by concern.** A single large state object forces every subscriber to re-render on any change:
+
+```tsx
+// Zustand — select only the slice you need
+const count = useStore((s) => s.cart.itemCount);
+
+// Jotai — one atom per concern
+const cartTotalAtom = atom((get) => {
+  const items = get(cartItemsAtom);
+  return items.reduce((sum, i) => sum + i.price * i.qty, 0);
+});
+```
+
+**React Compiler** (Expo SDK 54+) automatically memoizes components and hooks. Enable it to eliminate most manual `useMemo`/`useCallback`:
+
+```json
+// app.json
+{ "expo": { "experiments": { "reactCompiler": true } } }
+```
+
+### Deferred Updates
+
+When a state change triggers expensive computation (filtering a long list, rendering a complex tree), defer the update so typing or scrolling stays responsive:
+
+```tsx
+const [search, setSearch] = useState("");
+const deferred = useDeferredValue(search);
+
+const results = useMemo(
+  () => catalog.filter((p) => p.name.toLowerCase().includes(deferred.toLowerCase())),
+  [catalog, deferred],
+);
+```
+
+### TextInput on Android
+
+Controlled `TextInput` (with `value` + `onChangeText`) can lag on Android because every keystroke round-trips through the JS thread. For search bars or other high-frequency inputs, prefer uncontrolled mode:
+
+```tsx
+const ref = useRef<TextInput>(null);
+
+<TextInput
+  ref={ref}
+  defaultValue=""
+  onEndEditing={(e) => handleSearch(e.nativeEvent.text)}
+/>
+```
+
+## Startup Time (TTI)
+
+### Measuring
+
+```tsx
+import { PerformanceObserver, performance } from "react-native-performance";
+
+performance.mark("nativeLaunch");
+
+export default function App() {
+  useEffect(() => {
+    performance.measure("TTI", "nativeLaunch");
+  }, []);
+  // ...
+}
+```
+
+Always measure **cold starts** — kill the app completely before each measurement.
+
+### Reducing TTI
+
+- **Android bundle mmap** — Set `expo.useLegacyPackaging=false` in `android/gradle.properties` so Hermes memory-maps the bundle instead of decompressing it
+- **Preload heavy routes** — Call `preloadRouteAsync("/dashboard")` (from `expo-router`) while the user is still on the splash/login screen
+- **Lazy-load non-critical screens** — Screens behind deep navigation don't need to be in the initial bundle
+
+## Bundle & App Size
+
+### Inspecting the Bundle
+
+```bash
+npx expo export --platform ios --source-maps --output-dir dist
+npx source-map-explorer dist/bundles/ios/*.js
+```
+
+Common wins:
+- **Direct imports** — `import groupBy from "lodash/groupBy"` instead of `import { groupBy } from "lodash"`
+- **Remove dead Intl polyfills** — Hermes ships with built-in `Intl` support since SDK 50
+- **Tree shaking** — Enable via `"experiments": { "treeShaking": true }` in app config (SDK 52+)
+
+### Shrinking the Native Binary
+
+```properties
+# android/gradle.properties
+android.enableProguardInReleaseBuilds=true
+```
+
+Inspect the final artifact:
+- iOS: download the `.ipa` from EAS, unzip, check `Payload/*.app` size
+- Android: open the `.aab`/`.apk` in Android Studio → Build → Analyze APK
+
+## Memory
+
+### Preventing Leaks
+
+Every subscription, listener, or long-lived resource acquired in `useEffect` must be cleaned up:
+
+```tsx
+useEffect(() => {
+  const sub = AppState.addEventListener("change", onAppStateChange);
+  return () => sub.remove();
+}, []);
+```
+
+For fetch calls, pass an `AbortSignal` and abort on unmount:
+
+```tsx
+useEffect(() => {
+  const ac = new AbortController();
+  loadProducts(ac.signal);
+  return () => ac.abort();
+}, [categoryId]);
+```
+
+### Native Memory
+
+- Monitor with Xcode Memory Graph Debugger (iOS) or Android Studio Memory Profiler
+- Release heavy native resources (camera sessions, audio players) in cleanup
+- In Swift/Kotlin modules, watch for retain cycles — use `[weak self]` / `WeakReference`
+
+## Animations
+
+Only animate **`transform`** and **`opacity`**. These properties are composited on the GPU and don't trigger layout recalculation:
+
+```tsx
+const style = useAnimatedStyle(() => ({
+  opacity: withTiming(visible.value ? 1 : 0),
+  transform: [{ translateY: withSpring(offset.value) }],
+}));
+```
+
+Animating `width`, `height`, `margin`, `padding`, or `top`/`left` forces the layout engine to re-measure on every frame — a common source of dropped frames.
+
+Keep gesture callbacks on the UI thread:
+
+```tsx
+const drag = Gesture.Pan().onUpdate((e) => {
+  "worklet";
+  translateX.value = e.translationX;
+});
+```
+
+## Native Module Performance
+
+- Prefer **async** Turbo Module methods — synchronous calls block the JS thread
+- Use native SDK implementations over JS polyfills (`expo-crypto` over `crypto-js`, `react-native-mmkv` over AsyncStorage for hot paths)
+- **Android 16KB page alignment** is required for Google Play (2025+). Verify third-party `.so` files are compiled with 16KB alignment
+
+## Troubleshooting Guide
+
+| Symptom | Where to Look | Likely Fix |
+|---------|--------------|------------|
+| Scroll jank in long lists | JS thread — re-renders | Virtualized list + memoized items |
+| Typing lag in search bar | JS thread — controlled input | Uncontrolled `TextInput` with `defaultValue` |
+| Slow cold start | Bundle size, sync init | Mmap bundle, preload routes, lazy screens |
+| App binary too large | Native assets, unused libs | R8 (Android), analyze bundle, direct imports |
+| Growing memory over time | Effect cleanup | Return teardown from every `useEffect` |
+| Choppy enter/exit animation | Animated properties | Only `transform` + `opacity`, use worklets |
+| Re-renders cascade across app | Global state shape | Atomic selectors (Zustand/Jotai), React Compiler |

package/skills/react-native-dev/references/state-management.md

@@ -0,0 +1,230 @@
+# State Management Reference
+
+Patterns for local, shared, and server state in React Native / Expo apps.
+
+## Decision Guide
+
+| State Type | Solution |
+|------------|----------|
+| Local UI state (toggle, input) | `useState` / `useReducer` |
+| Shared app-wide state | Zustand or Jotai |
+| Server/async data | React Query (TanStack Query) |
+| Form state | React Hook Form (see forms.md) |
+| Auth / session | Zustand + `expo-secure-store` |
+
+**Avoid**: Redux for new projects (boilerplate), Context for high-frequency updates (re-render overhead).
+
+## useState / useReducer
+
+```tsx
+// Simple toggle
+const [isOpen, setIsOpen] = useState(false);
+
+// Complex local state — useReducer
+type State = { count: number; status: "idle" | "loading" | "error" };
+type Action = { type: "increment" } | { type: "setStatus"; payload: State["status"] };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case "increment": return { ...state, count: state.count + 1 };
+    case "setStatus": return { ...state, status: action.payload };
+  }
+}
+
+const [state, dispatch] = useReducer(reducer, { count: 0, status: "idle" });
+dispatch({ type: "increment" });
+```
+
+## Zustand (Shared State)
+
+```bash
+npx expo install zustand
+```
+
+```tsx
+// stores/settings-store.ts
+import { create } from "zustand";
+import { persist, createJSONStorage } from "zustand/middleware";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+interface SettingsStore {
+  theme: "light" | "dark";
+  locale: string;
+  setTheme: (theme: "light" | "dark") => void;
+  setLocale: (locale: string) => void;
+}
+
+export const useSettingsStore = create<SettingsStore>()(
+  persist(
+    (set) => ({
+      theme: "light",
+      locale: "en",
+      setTheme: (theme) => set({ theme }),
+      setLocale: (locale) => set({ locale }),
+    }),
+    {
+      name: "settings-storage",
+      storage: createJSONStorage(() => AsyncStorage),
+    }
+  )
+);
+
+// Usage
+const { theme, setTheme } = useSettingsStore();
+const locale = useSettingsStore((s) => s.locale); // Selector — minimizes re-renders
+```
+
+```tsx
+// stores/cart-store.ts
+interface CartStore {
+  items: CartItem[];
+  add: (product: Product) => void;
+  remove: (id: string) => void;
+  clear: () => void;
+  total: () => number;
+}
+
+export const useCartStore = create<CartStore>()((set, get) => ({
+  items: [],
+  add: (product) => set((s) => ({
+    items: [...s.items, { product, quantity: 1 }],
+  })),
+  remove: (id) => set((s) => ({
+    items: s.items.filter((i) => i.product.id !== id),
+  })),
+  clear: () => set({ items: [] }),
+  total: () => get().items.reduce((sum, i) => sum + i.product.price * i.quantity, 0),
+}));
+```
+
+## Jotai (Atomic State)
+
+```bash
+npx expo install jotai
+```
+
+```tsx
+// atoms/user-atoms.ts
+import { atom } from "jotai";
+import { atomWithStorage, createJSONStorage } from "jotai/utils";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const storage = createJSONStorage(() => AsyncStorage);
+
+export const userAtom = atom<User | null>(null);
+export const themeAtom = atomWithStorage<"light" | "dark">("theme", "light", storage);
+
+// Derived atom — computed from others
+export const isAdminAtom = atom((get) => get(userAtom)?.role === "admin");
+```
+
+```tsx
+// Usage — component only re-renders when its atoms change
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
+
+function Header() {
+  const user = useAtomValue(userAtom);         // read-only
+  const setTheme = useSetAtom(themeAtom);      // write-only
+  const [theme, setThemeRW] = useAtom(themeAtom); // read + write
+  return <Text>{user?.name}</Text>;
+}
+```
+
+**Zustand vs Jotai**:
+- **Zustand** — store-based, better for related state with actions (auth, cart)
+- **Jotai** — atom-based, better for independent values, fine-grained subscriptions, avoids re-renders
+
+## React Query (Server State)
+
+See [networking.md](networking.md) for full reference. Key patterns:
+
+```tsx
+// Queries — read
+const { data, isLoading } = useQuery({ queryKey: ["users"], queryFn: fetchUsers });
+
+// Mutations — write
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["users"] }),
+});
+
+// Optimistic update
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async (newUser) => {
+    await queryClient.cancelQueries({ queryKey: ["user", newUser.id] });
+    const prev = queryClient.getQueryData(["user", newUser.id]);
+    queryClient.setQueryData(["user", newUser.id], newUser);
+    return { prev };
+  },
+  onError: (_err, variables, context) => {
+    queryClient.setQueryData(["user", variables.id], context?.prev);
+  },
+});
+```
+
+## Minimize Re-renders
+
+### Zustand Selectors
+
+```tsx
+// ✗ Wrong — re-renders on any store change
+const store = useAuthStore();
+
+// ✓ Correct — re-renders only when user changes
+const user = useAuthStore((s) => s.user);
+const logout = useAuthStore((s) => s.logout); // Actions are stable references
+```
+
+### Dispatcher Pattern
+
+```tsx
+// ✗ Wrong — passes callbacks that recreate on every render
+function Parent() {
+  const [count, setCount] = useState(0);
+  return <Child onIncrement={() => setCount(c => c + 1)} />;
+}
+
+// ✓ Correct — dispatcher reference is stable
+function Parent() {
+  const [count, dispatch] = useReducer(reducer, 0);
+  return <Child dispatch={dispatch} />;
+}
+```
+
+### React Compiler (SDK 54+)
+
+With React Compiler enabled, `memo`, `useCallback`, and `useMemo` are often unnecessary:
+
+```json
+// app.json
+{ "expo": { "experiments": { "reactCompiler": true } } }
+```
+
+## Context (Use Sparingly)
+
+Context is suitable for infrequently-changing values (theme, locale, auth status). **Avoid** for high-frequency updates like scroll position or form input.
+
+```tsx
+const ThemeContext = createContext<"light" | "dark">("light");
+
+function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<"light" | "dark">("light");
+  return <ThemeContext value={theme}>{children}</ThemeContext>; // React 19+
+}
+
+// Consume
+const theme = use(ThemeContext); // React 19+
+```
+
+## Fallback on First Render
+
+```tsx
+// ✓ Always show fallback while async state loads
+function UserProfile({ userId }: { userId: string }) {
+  const { data, isLoading } = useQuery({ queryKey: ["user", userId], queryFn: () => fetchUser(userId) });
+  if (isLoading) return <UserProfileSkeleton />;
+  if (!data) return null;
+  return <Profile user={data} />;
+}
+```

package/skills/react-native-dev/references/styling.md

@@ -0,0 +1,117 @@
+# Styling Reference
+
+StyleSheet, NativeWind/Tailwind, platform-specific styles, and theming for Expo/React Native.
+
+## StyleSheet
+
+```tsx
+import { StyleSheet } from "react-native";
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: "#fff" },
+  text: { fontSize: 16, fontWeight: "600" },
+});
+```
+
+Prefer `StyleSheet.create` over inline style objects — it validates styles at creation time and enables potential future optimizations.
+
+## Platform-Specific Styles
+
+```tsx
+import { Platform, StyleSheet } from "react-native";
+
+const styles = StyleSheet.create({
+  shadow: Platform.select({
+    ios: { shadowColor: "#000", shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1, shadowRadius: 4 },
+    android: { elevation: 4 },
+  }),
+});
+```
+
+Since React Native 0.76+, `boxShadow` is supported as a unified cross-platform shadow API. Prefer it over platform-specific shadow properties when targeting New Architecture.
+
+## NativeWind / Tailwind CSS
+
+For existing projects, check which NativeWind version is in `package.json` and follow the corresponding docs. For new projects, use NativeWind v4 (stable).
+
+### Installation (NativeWind v4)
+
+```bash
+npx expo install nativewind tailwindcss@3 \
+  tailwind-merge clsx
+```
+
+### Configuration
+
+```js
+// babel.config.js
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ["babel-preset-expo"],
+    plugins: ["nativewind/babel"],
+  };
+};
+```
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
+  presets: [require("nativewind/preset")],
+  theme: { extend: {} },
+};
+```
+
+```css
+/* global.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+```tsx
+// app/_layout.tsx
+import "../global.css";
+```
+
+### Usage
+
+```tsx
+<View className="flex-1 bg-white p-4">
+  <Text className="text-lg font-semibold text-gray-900">Title</Text>
+  <Pressable className="mt-4 rounded-lg bg-blue-500 px-4 py-2">
+    <Text className="text-center text-white font-medium">Button</Text>
+  </Pressable>
+</View>
+```
+
+### Conditional Classes
+
+```tsx
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));
+
+<View className={cn("p-4", isActive && "bg-blue-500", isDisabled && "opacity-50")} />
+```
+
+## Theming and Dark Mode
+
+For apps using NativeWind, use Tailwind's `dark:` variant:
+
+```tsx
+<View className="bg-white dark:bg-gray-900">
+  <Text className="text-gray-900 dark:text-white">Adaptive text</Text>
+</View>
+```
+
+For StyleSheet-based projects, read the system color scheme and map it to a theme object:
+
+```tsx
+import { useColorScheme } from "react-native";
+
+const colorScheme = useColorScheme(); // "light" | "dark"
+```
+
+Keep color tokens in a central `constants/colors.ts` file with light and dark variants. Pass the active palette via React Context or a Zustand store.