@ivannxbt/ai-config 0.1.0

package/.agents/skills/expo-react-native-performance/references/asset-use-webp-format.md

@@ -0,0 +1,50 @@
+---
+title: Use WebP Format for Images
+impact: MEDIUM-HIGH
+impactDescription: 25-35% smaller than JPEG at same quality
+tags: asset, webp, format, compression
+---
+
+## Use WebP Format for Images
+
+WebP provides superior compression compared to JPEG and PNG while maintaining quality. Serve WebP images to reduce bandwidth and improve load times.
+
+**Incorrect (using JPEG/PNG):**
+
+```typescript
+// assets/images.ts
+export const images = {
+  hero: require('./hero.jpg'),      // 450KB
+  product: require('./product.png'), // 280KB
+  background: require('./bg.jpg'),   // 320KB
+};
+// Total: 1050KB
+```
+
+**Correct (using WebP):**
+
+```typescript
+// assets/images.ts
+export const images = {
+  hero: require('./hero.webp'),      // 290KB (35% smaller)
+  product: require('./product.webp'), // 180KB (36% smaller)
+  background: require('./bg.webp'),   // 210KB (34% smaller)
+};
+// Total: 680KB (35% reduction)
+```
+
+**Converting existing images:**
+
+```bash
+# Using cwebp (install via Homebrew)
+cwebp -q 80 input.jpg -o output.webp
+
+# Batch convert with expo-optimize
+npx expo-optimize ./assets
+```
+
+**For remote images:** Request WebP from CDN with `f_auto` or `auto=format` parameter.
+
+**Compatibility:** WebP is supported on iOS 14+ and all Android versions. For older iOS, provide JPEG fallback.
+
+Reference: [expo-optimize](https://www.npmjs.com/package/expo-optimize)

package/.agents/skills/expo-react-native-performance/references/async-batch-api-calls.md

@@ -0,0 +1,65 @@
+---
+title: Batch Related API Calls
+impact: MEDIUM
+impactDescription: reduces N requests to 1
+tags: async, batching, api, network
+---
+
+## Batch Related API Calls
+
+Making individual API calls for each item creates N network requests. Batch items into a single call when your API supports it to dramatically reduce latency.
+
+**Incorrect (N requests for N items):**
+
+```typescript
+// screens/FriendsActivity.tsx
+export function FriendsActivity({ friendIds }: Props) {
+  const [activities, setActivities] = useState<Activity[]>([]);
+
+  useEffect(() => {
+    async function loadActivities() {
+      // 10 friends = 10 API calls = 10 round trips
+      const results = await Promise.all(
+        friendIds.map((id) => fetchActivity(id))
+      );
+      setActivities(results.flat());
+    }
+    loadActivities();
+  }, [friendIds]);
+
+  return <ActivityFeed activities={activities} />;
+}
+// 10 requests × 100ms each = 1000ms (even with parallelization)
+```
+
+**Correct (1 batched request):**
+
+```typescript
+// screens/FriendsActivity.tsx
+export function FriendsActivity({ friendIds }: Props) {
+  const [activities, setActivities] = useState<Activity[]>([]);
+
+  useEffect(() => {
+    async function loadActivities() {
+      // Single API call with all IDs
+      const results = await fetchActivities(friendIds);
+      setActivities(results);
+    }
+    loadActivities();
+  }, [friendIds]);
+
+  return <ActivityFeed activities={activities} />;
+}
+// 1 request × 150ms = 150ms (85% faster)
+```
+
+**API design pattern:**
+
+```typescript
+// Instead of: GET /activity/:userId (called N times)
+// Use: POST /activities/batch with { userIds: string[] }
+```
+
+**Client-side batching:** Libraries like `dataloader` can automatically batch calls within a time window.
+
+Reference: [DataLoader](https://github.com/graphql/dataloader)

package/.agents/skills/expo-react-native-performance/references/async-cache-responses.md

@@ -0,0 +1,54 @@
+---
+title: Cache API Responses Locally
+impact: MEDIUM
+impactDescription: eliminates redundant network requests
+tags: async, caching, tanstack-query, swr
+---
+
+## Cache API Responses Locally
+
+Repeated API calls for the same data waste bandwidth and slow down the app. Use a caching library to store and reuse responses.
+
+**Incorrect (fetch on every mount):**
+
+```typescript
+// screens/ProductDetails.tsx
+export function ProductDetails({ productId }: Props) {
+  const [product, setProduct] = useState<Product | null>(null);
+
+  useEffect(() => {
+    fetchProduct(productId).then(setProduct);
+  }, [productId]);
+
+  // User navigates away and back: fetches again
+  return product ? <ProductView product={product} /> : <Loading />;
+}
+// Same product fetched every time user visits this screen
+```
+
+**Correct (cached with TanStack Query):**
+
+```typescript
+// screens/ProductDetails.tsx
+import { useQuery } from '@tanstack/react-query';
+
+export function ProductDetails({ productId }: Props) {
+  const { data: product, isLoading } = useQuery({
+    queryKey: ['product', productId],
+    queryFn: () => fetchProduct(productId),
+    staleTime: 5 * 60 * 1000,  // Consider fresh for 5 minutes
+  });
+
+  // Instant display on return visit, background refetch if stale
+  return product ? <ProductView product={product} /> : <Loading />;
+}
+// Cached response shown immediately, refetches in background
+```
+
+**Benefits of caching libraries:**
+- Automatic deduplication of in-flight requests
+- Background refetching when data is stale
+- Optimistic updates for mutations
+- Request retry on failure
+
+Reference: [TanStack Query](https://tanstack.com/query/latest)

package/.agents/skills/expo-react-native-performance/references/async-defer-await.md

@@ -0,0 +1,56 @@
+---
+title: Defer await Until Value Needed
+impact: MEDIUM
+impactDescription: 20-50% faster by overlapping async work
+tags: async, defer, promises, optimization
+---
+
+## Defer await Until Value Needed
+
+Start promises immediately but defer `await` until you actually need the value. This allows intermediate synchronous code to run while the promise is pending.
+
+**Incorrect (await blocks immediately):**
+
+```typescript
+// screens/CheckoutScreen.tsx
+export async function processCheckout(cartId: string, userId: string) {
+  const cart = await fetchCart(cartId);  // Blocks here
+
+  // Sync validation could run while cart fetches
+  const shippingValid = validateShippingAddress(userId);
+  if (!shippingValid) throw new Error('Invalid shipping');
+
+  const inventory = await checkInventory(cart.items);  // Blocks here
+  return { cart, inventory };
+}
+```
+
+**Correct (start early, await late):**
+
+```typescript
+// screens/CheckoutScreen.tsx
+export async function processCheckout(cartId: string, userId: string) {
+  // Start both fetches immediately
+  const cartPromise = fetchCart(cartId);
+  const inventoryCheck = async () => {
+    const cart = await cartPromise;
+    return checkInventory(cart.items);
+  };
+
+  // Sync validation runs while cart fetches
+  const shippingValid = validateShippingAddress(userId);
+  if (!shippingValid) throw new Error('Invalid shipping');
+
+  // Now await only when we need the values
+  const [cart, inventory] = await Promise.all([
+    cartPromise,
+    inventoryCheck(),
+  ]);
+
+  return { cart, inventory };
+}
+```
+
+**Key insight:** The promise starts executing when called, not when awaited. Use this to overlap network and computation.
+
+Reference: [Async/Await Best Practices](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises)

package/.agents/skills/expo-react-native-performance/references/async-parallel-fetching.md

@@ -0,0 +1,60 @@
+---
+title: Fetch Independent Data in Parallel
+impact: MEDIUM
+impactDescription: 2-5× faster screen load time
+tags: async, parallel, Promise.all, waterfalls
+---
+
+## Fetch Independent Data in Parallel
+
+Sequential awaits create network waterfalls where each request waits for the previous to complete. Use `Promise.all()` for independent requests to run them concurrently.
+
+**Incorrect (sequential requests, 3 round trips):**
+
+```typescript
+// screens/Dashboard.tsx
+export function Dashboard({ userId }: Props) {
+  const [data, setData] = useState<DashboardData | null>(null);
+
+  useEffect(() => {
+    async function loadData() {
+      const user = await fetchUser(userId);
+      const orders = await fetchOrders(userId);
+      const notifications = await fetchNotifications(userId);
+      setData({ user, orders, notifications });
+    }
+    loadData();
+  }, [userId]);
+
+  return data ? <DashboardView data={data} /> : <Loading />;
+}
+// Total time: user + orders + notifications (e.g., 300 + 400 + 200 = 900ms)
+```
+
+**Correct (parallel requests, 1 round trip):**
+
+```typescript
+// screens/Dashboard.tsx
+export function Dashboard({ userId }: Props) {
+  const [data, setData] = useState<DashboardData | null>(null);
+
+  useEffect(() => {
+    async function loadData() {
+      const [user, orders, notifications] = await Promise.all([
+        fetchUser(userId),
+        fetchOrders(userId),
+        fetchNotifications(userId),
+      ]);
+      setData({ user, orders, notifications });
+    }
+    loadData();
+  }, [userId]);
+
+  return data ? <DashboardView data={data} /> : <Loading />;
+}
+// Total time: max(user, orders, notifications) (e.g., 400ms)
+```
+
+**When NOT to parallelize:** When requests depend on each other (e.g., need user.id for orders).
+
+Reference: [Promise.all](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)

package/.agents/skills/expo-react-native-performance/references/async-refetch-on-focus.md

@@ -0,0 +1,68 @@
+---
+title: Refetch Data on Screen Focus
+impact: MEDIUM
+impactDescription: prevents stale data after hours in background
+tags: async, focus, refetch, navigation
+---
+
+## Refetch Data on Screen Focus
+
+Mobile apps stay in background for extended periods. Refetch important data when the screen becomes focused to ensure users see current information.
+
+**Incorrect (data stale after background):**
+
+```typescript
+// screens/NotificationsScreen.tsx
+export function NotificationsScreen() {
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+
+  useEffect(() => {
+    fetchNotifications().then(setNotifications);
+  }, []);
+
+  // User backgrounds app, returns hours later, sees stale notifications
+  return <NotificationList notifications={notifications} />;
+}
+```
+
+**Correct (refetch on screen focus):**
+
+```typescript
+// screens/NotificationsScreen.tsx
+import { useFocusEffect } from '@react-navigation/native';
+
+export function NotificationsScreen() {
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+
+  useFocusEffect(
+    useCallback(() => {
+      fetchNotifications().then(setNotifications);
+    }, [])
+  );
+
+  // Fresh data loaded every time screen becomes visible
+  return <NotificationList notifications={notifications} />;
+}
+```
+
+**With TanStack Query (automatic):**
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { useFocusEffect } from '@react-navigation/native';
+
+export function NotificationsScreen() {
+  const { data: notifications, refetch } = useQuery({
+    queryKey: ['notifications'],
+    queryFn: fetchNotifications,
+  });
+
+  useFocusEffect(useCallback(() => { refetch(); }, [refetch]));
+
+  return <NotificationList notifications={notifications ?? []} />;
+}
+```
+
+**Note:** Balance freshness with performance. Not every screen needs refetch on focus.
+
+Reference: [useFocusEffect](https://reactnavigation.org/docs/use-focus-effect/)

package/.agents/skills/expo-react-native-performance/references/list-estimated-item-size.md

@@ -0,0 +1,52 @@
+---
+title: Provide Accurate estimatedItemSize
+impact: CRITICAL
+impactDescription: prevents blank cells during fast scroll
+tags: list, flashlist, estimated-size, virtualization
+---
+
+## Provide Accurate estimatedItemSize
+
+FlashList uses `estimatedItemSize` to calculate how many items to render initially and during scroll. An inaccurate estimate causes blank cells or excessive memory usage. Measure your actual item height and provide it.
+
+**Incorrect (default or guessed estimate):**
+
+```typescript
+// screens/MessageList.tsx
+export function MessageList({ messages }: Props) {
+  return (
+    <FlashList
+      data={messages}
+      renderItem={({ item }) => <MessageBubble message={item} />}
+      estimatedItemSize={50}  // Wrong: actual messages are ~150px tall
+    />
+    // Blank cells appear during fast scrolling
+  );
+}
+```
+
+**Correct (measured average height):**
+
+```typescript
+// screens/MessageList.tsx
+export function MessageList({ messages }: Props) {
+  return (
+    <FlashList
+      data={messages}
+      renderItem={({ item }) => <MessageBubble message={item} />}
+      estimatedItemSize={150}  // Measured from actual rendered items
+    />
+    // Smooth scrolling with no blank cells
+  );
+}
+```
+
+**How to measure:**
+1. Add `onLayout` to your list item temporarily
+2. Log the `event.nativeEvent.layout.height`
+3. Average across multiple items
+4. Use the median value for varied-height lists
+
+**For mixed content:** Use the average height. FlashList v2 removes the need for estimates entirely.
+
+Reference: [FlashList estimatedItemSize](https://shopify.github.io/flash-list/docs/fundamentals/performant-components)

package/.agents/skills/expo-react-native-performance/references/list-get-item-layout.md

@@ -0,0 +1,64 @@
+---
+title: Provide getItemLayout for Fixed Heights
+impact: CRITICAL
+impactDescription: eliminates async layout calculation
+tags: list, flatlist, layout, fixed-height
+---
+
+## Provide getItemLayout for Fixed Heights
+
+When all list items have the same height, provide `getItemLayout` to skip asynchronous measurement. FlatList/FlashList can instantly calculate scroll position without rendering off-screen items.
+
+**Incorrect (FlatList measures each item):**
+
+```typescript
+// screens/NotificationList.tsx
+const ITEM_HEIGHT = 72;
+
+export function NotificationList({ notifications }: Props) {
+  return (
+    <FlatList
+      data={notifications}
+      renderItem={({ item }) => (
+        <NotificationRow notification={item} style={{ height: ITEM_HEIGHT }} />
+      )}
+      keyExtractor={(item) => item.id}
+    />
+    // FlatList renders items to measure them, causing scroll jank
+  );
+}
+```
+
+**Correct (skip measurement with getItemLayout):**
+
+```typescript
+// screens/NotificationList.tsx
+const ITEM_HEIGHT = 72;
+
+export function NotificationList({ notifications }: Props) {
+  const getItemLayout = useCallback(
+    (_: any, index: number) => ({
+      length: ITEM_HEIGHT,
+      offset: ITEM_HEIGHT * index,
+      index,
+    }),
+    []
+  );
+
+  return (
+    <FlatList
+      data={notifications}
+      renderItem={({ item }) => (
+        <NotificationRow notification={item} style={{ height: ITEM_HEIGHT }} />
+      )}
+      keyExtractor={(item) => item.id}
+      getItemLayout={getItemLayout}
+    />
+    // Instant scroll position calculation, no measurement needed
+  );
+}
+```
+
+**When NOT to use:** Items with dynamic heights (text wrapping, images). Use FlashList with `estimatedItemSize` instead.
+
+Reference: [Optimizing FlatList](https://reactnative.dev/docs/optimizing-flatlist-configuration)

package/.agents/skills/expo-react-native-performance/references/list-get-item-type.md

@@ -0,0 +1,59 @@
+---
+title: Use getItemType for Mixed Lists
+impact: CRITICAL
+impactDescription: 50% better recycling efficiency
+tags: list, flashlist, item-type, heterogeneous
+---
+
+## Use getItemType for Mixed Lists
+
+When a list contains different component types (headers, items, ads), FlashList can only recycle views of the same type. Provide `getItemType` to help FlashList maintain separate recycling pools for each type.
+
+**Incorrect (no type differentiation):**
+
+```typescript
+// screens/Feed.tsx
+type FeedItem = { type: 'post' | 'ad' | 'header'; data: any };
+
+export function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <FlashList
+      data={items}
+      renderItem={({ item }) => {
+        if (item.type === 'header') return <SectionHeader data={item.data} />;
+        if (item.type === 'ad') return <AdBanner data={item.data} />;
+        return <PostCard data={item.data} />;
+      }}
+      estimatedItemSize={200}
+    />
+    // FlashList can't recycle: header view becomes post view = layout thrashing
+  );
+}
+```
+
+**Correct (typed recycling pools):**
+
+```typescript
+// screens/Feed.tsx
+type FeedItem = { type: 'post' | 'ad' | 'header'; data: any };
+
+export function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <FlashList
+      data={items}
+      renderItem={({ item }) => {
+        if (item.type === 'header') return <SectionHeader data={item.data} />;
+        if (item.type === 'ad') return <AdBanner data={item.data} />;
+        return <PostCard data={item.data} />;
+      }}
+      getItemType={(item) => item.type}
+      estimatedItemSize={200}
+    />
+    // Posts recycle into posts, headers into headers
+  );
+}
+```
+
+**Result:** Each type maintains its own recycling pool, preventing expensive layout recalculations when items of different heights are recycled.
+
+Reference: [FlashList getItemType](https://shopify.github.io/flash-list/docs/fundamentals/performant-components)

package/.agents/skills/expo-react-native-performance/references/list-memoize-items.md

@@ -0,0 +1,59 @@
+---
+title: Memoize List Item Components
+impact: CRITICAL
+impactDescription: prevents re-render of unchanged items
+tags: list, memo, react-memo, item-component
+---
+
+## Memoize List Item Components
+
+Wrap list item components in `React.memo()` to prevent re-rendering when their props haven't changed. Without memoization, all visible items re-render whenever the parent component updates.
+
+**Incorrect (item re-renders on every list update):**
+
+```typescript
+// components/ProductCard.tsx
+interface ProductCardProps {
+  product: Product;
+  onPress: (id: string) => void;
+}
+
+export function ProductCard({ product, onPress }: ProductCardProps) {
+  return (
+    <Pressable onPress={() => onPress(product.id)}>
+      <Image source={{ uri: product.imageUrl }} style={styles.image} />
+      <Text>{product.name}</Text>
+      <Text>${product.price}</Text>
+    </Pressable>
+  );
+}
+// Every card re-renders when any card changes
+```
+
+**Correct (memoized item only re-renders on prop change):**
+
+```typescript
+// components/ProductCard.tsx
+interface ProductCardProps {
+  product: Product;
+  onPress: (id: string) => void;
+}
+
+export const ProductCard = memo(function ProductCard({
+  product,
+  onPress,
+}: ProductCardProps) {
+  return (
+    <Pressable onPress={() => onPress(product.id)}>
+      <Image source={{ uri: product.imageUrl }} style={styles.image} />
+      <Text>{product.name}</Text>
+      <Text>${product.price}</Text>
+    </Pressable>
+  );
+});
+// Only re-renders if product or onPress reference changes
+```
+
+**Important:** Ensure `onPress` is stable (use `useCallback`) or memo won't help since the function reference changes every render.
+
+Reference: [React.memo](https://react.dev/reference/react/memo)

package/.agents/skills/expo-react-native-performance/references/list-stable-render-item.md

@@ -0,0 +1,61 @@
+---
+title: Stabilize renderItem with useCallback
+impact: CRITICAL
+impactDescription: prevents full list re-render on parent update
+tags: list, useCallback, render-item, stability
+---
+
+## Stabilize renderItem with useCallback
+
+Defining `renderItem` inline creates a new function on every render, causing FlashList/FlatList to think the renderer changed and re-render all visible items. Extract and memoize the render function.
+
+**Incorrect (inline renderItem recreated every render):**
+
+```typescript
+// screens/ContactList.tsx
+export function ContactList({ contacts }: Props) {
+  const [searchQuery, setSearchQuery] = useState('');
+
+  return (
+    <>
+      <SearchInput value={searchQuery} onChangeText={setSearchQuery} />
+      <FlashList
+        data={filteredContacts}
+        renderItem={({ item }) => (
+          <ContactRow contact={item} />
+        )}  // New function on every keystroke = all rows re-render
+        estimatedItemSize={60}
+      />
+    </>
+  );
+}
+```
+
+**Correct (stable renderItem with useCallback):**
+
+```typescript
+// screens/ContactList.tsx
+export function ContactList({ contacts }: Props) {
+  const [searchQuery, setSearchQuery] = useState('');
+
+  const renderContact = useCallback(
+    ({ item }: { item: Contact }) => <ContactRow contact={item} />,
+    []
+  );
+
+  return (
+    <>
+      <SearchInput value={searchQuery} onChangeText={setSearchQuery} />
+      <FlashList
+        data={filteredContacts}
+        renderItem={renderContact}
+        estimatedItemSize={60}
+      />
+    </>
+  );
+}
+```
+
+**Important:** If `renderItem` uses callbacks like `onPress`, include them in the dependency array or use functional updates to avoid stale closures.
+
+Reference: [Optimizing FlatList](https://reactnative.dev/docs/optimizing-flatlist-configuration)