@olives/devos 2.1.0

package/.agents/skills/vercel-react-native-skills/rules/list-performance-item-types.md

@@ -0,0 +1,104 @@
+---
+title: Use Item Types for Heterogeneous Lists
+impact: HIGH
+impactDescription: efficient recycling, less layout thrashing
+tags: list, performance, recycling, heterogeneous, LegendList
+---
+
+## Use Item Types for Heterogeneous Lists
+
+When a list has different item layouts (messages, images, headers, etc.), use a
+`type` field on each item and provide `getItemType` to the list. This puts items
+into separate recycling pools so a message component never gets recycled into an
+image component.
+
+**Incorrect (single component with conditionals):**
+
+```tsx
+type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
+
+function ListItem({ item }: { item: Item }) {
+  if (item.isHeader) {
+    return <HeaderItem title={item.text} />
+  }
+  if (item.imageUrl) {
+    return <ImageItem url={item.imageUrl} />
+  }
+  return <MessageItem text={item.text} />
+}
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      renderItem={({ item }) => <ListItem item={item} />}
+      recycleItems
+    />
+  )
+}
+```
+
+**Correct (typed items with separate components):**
+
+```tsx
+type HeaderItem = { id: string; type: 'header'; title: string }
+type MessageItem = { id: string; type: 'message'; text: string }
+type ImageItem = { id: string; type: 'image'; url: string }
+type FeedItem = HeaderItem | MessageItem | ImageItem
+
+function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <LegendList
+      data={items}
+      keyExtractor={(item) => item.id}
+      getItemType={(item) => item.type}
+      renderItem={({ item }) => {
+        switch (item.type) {
+          case 'header':
+            return <SectionHeader title={item.title} />
+          case 'message':
+            return <MessageRow text={item.text} />
+          case 'image':
+            return <ImageRow url={item.url} />
+        }
+      }}
+      recycleItems
+    />
+  )
+}
+```
+
+**Why this matters:**
+
+- **Recycling efficiency**: Items with the same type share a recycling pool
+- **No layout thrashing**: A header never recycles into an image cell
+- **Type safety**: TypeScript can narrow the item type in each branch
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+  accurate estimates per type
+
+```tsx
+<LegendList
+  data={items}
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type}
+  getEstimatedItemSize={(index, item, itemType) => {
+    switch (itemType) {
+      case 'header':
+        return 48
+      case 'message':
+        return 72
+      case 'image':
+        return 300
+      default:
+        return 72
+    }
+  }}
+  renderItem={({ item }) => {
+    /* ... */
+  }}
+  recycleItems
+/>
+```
+
+Reference:
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)

package/.agents/skills/vercel-react-native-skills/rules/list-performance-virtualize.md

@@ -0,0 +1,67 @@
+---
+title: Use a List Virtualizer for Any List
+impact: HIGH
+impactDescription: reduced memory, faster mounts
+tags: lists, performance, virtualization, scrollview
+---
+
+## Use a List Virtualizer for Any List
+
+Use a list virtualizer like LegendList or FlashList instead of ScrollView with
+mapped children—even for short lists. Virtualizers only render visible items,
+reducing memory usage and mount time. ScrollView renders all children upfront,
+which gets expensive quickly.
+
+**Incorrect (ScrollView renders all items at once):**
+
+```tsx
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <ScrollView>
+      {items.map((item) => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </ScrollView>
+  )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct (virtualizer renders only visible items):**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+      estimatedItemSize={80}
+    />
+  )
+}
+// Only ~10-15 visible items mounted at a time
+```
+
+**Alternative (FlashList):**
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <FlashList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+    />
+  )
+}
+```
+
+Benefits apply to any screen with scrollable content—profiles, settings, feeds,
+search results. Default to virtualization.

package/.agents/skills/vercel-react-native-skills/rules/monorepo-native-deps-in-app.md

@@ -0,0 +1,46 @@
+---
+title: Install Native Dependencies in App Directory
+impact: CRITICAL
+impactDescription: required for autolinking to work
+tags: monorepo, native, autolinking, installation
+---
+
+## Install Native Dependencies in App Directory
+
+In a monorepo, packages with native code must be installed in the native app's
+directory directly. Autolinking only scans the app's `node_modules`—it won't
+find native dependencies installed in other packages.
+
+**Incorrect (native dep in shared package only):**
+
+```
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # missing react-native-reanimated
+```
+
+Autolinking fails—native code not linked.
+
+**Correct (native dep in app directory):**
+
+```
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # also has react-native-reanimated
+```
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Even if the shared package uses the native dependency, the app must also list it
+for autolinking to detect and link the native code.

package/.agents/skills/vercel-react-native-skills/rules/monorepo-single-dependency-versions.md

@@ -0,0 +1,63 @@
+---
+title: Use Single Dependency Versions Across Monorepo
+impact: MEDIUM
+impactDescription: avoids duplicate bundles, version conflicts
+tags: monorepo, dependencies, installation
+---
+
+## Use Single Dependency Versions Across Monorepo
+
+Use a single version of each dependency across all packages in your monorepo.
+Prefer exact versions over ranges. Multiple versions cause duplicate code in
+bundles, runtime conflicts, and inconsistent behavior across packages.
+
+Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions
+or npm overrides.
+
+**Incorrect (version ranges, multiple versions):**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.0.0"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.5.0"
+  }
+}
+```
+
+**Correct (exact versions, single source of truth):**
+
+```json
+// package.json (root)
+{
+  "pnpm": {
+    "overrides": {
+      "react-native-reanimated": "3.16.1"
+    }
+  }
+}
+
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Use your package manager's override/resolution feature to enforce versions at
+the root. When adding dependencies, specify exact versions without `^` or `~`.

package/.agents/skills/vercel-react-native-skills/rules/navigation-native-navigators.md

@@ -0,0 +1,188 @@
+---
+title: Use Native Navigators for Navigation
+impact: HIGH
+impactDescription: native performance, platform-appropriate UI
+tags: navigation, react-navigation, expo-router, native-stack, tabs
+---
+
+## Use Native Navigators for Navigation
+
+Always use native navigators instead of JS-based ones. Native navigators use
+platform APIs (UINavigationController on iOS, Fragment on Android) for better
+performance and native behavior.
+
+**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
+stack (which uses native-stack). Avoid `@react-navigation/stack`.
+
+**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
+tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
+
+### Stack Navigation
+
+**Incorrect (JS stack navigator):**
+
+```tsx
+import { createStackNavigator } from '@react-navigation/stack'
+
+const Stack = createStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct (native stack with react-navigation):**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct (expo-router uses native stack by default):**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+  return <Stack />
+}
+```
+
+### Tab Navigation
+
+**Incorrect (JS bottom tabs):**
+
+```tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
+
+const Tab = createBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen name='Home' component={HomeScreen} />
+      <Tab.Screen name='Settings' component={SettingsScreen} />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct (native bottom tabs with react-navigation):**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name='Home'
+        component={HomeScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'house' }),
+        }}
+      />
+      <Tab.Screen
+        name='Settings'
+        component={SettingsScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'gear' }),
+        }}
+      />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct (expo-router native tabs):**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name='index'>
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name='settings'>
+        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+behind the translucent tab bar. If you need to disable this, use
+`disableAutomaticContentInsets` on the trigger.
+
+### Prefer Native Header Options Over Custom Components
+
+**Incorrect (custom header component):**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    header: () => <CustomHeader title='Profile' />,
+  }}
+/>
+```
+
+**Correct (native header options):**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    title: 'Profile',
+    headerLargeTitleEnabled: true,
+    headerSearchBarOptions: {
+      placeholder: 'Search',
+    },
+  }}
+/>
+```
+
+Native headers support iOS large titles, search bars, blur effects, and proper
+safe area handling automatically.
+
+### Why Native Navigators
+
+- **Performance**: Native transitions and gestures run on the UI thread
+- **Platform behavior**: Automatic iOS large titles, Android material design
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+  areas
+- **Accessibility**: Platform accessibility features work automatically
+
+Reference:
+
+- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
+- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)

package/.agents/skills/vercel-react-native-skills/rules/react-compiler-destructure-functions.md

@@ -0,0 +1,50 @@
+---
+title: Destructure Functions Early in Render (React Compiler)
+impact: HIGH
+impactDescription: stable references, fewer re-renders
+tags: rerender, hooks, performance, react-compiler
+---
+
+## Destructure Functions Early in Render
+
+This rule is only applicable if you are using the React Compiler.
+
+Destructure functions from hooks at the top of render scope. Never dot into
+objects to call functions. Destructured functions are stable references; dotting
+creates new references and breaks memoization.
+
+**Incorrect (dotting into object):**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton(props) {
+  const router = useRouter()
+
+  // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render
+  const handlePress = () => {
+    props.onSave()
+    router.push('/success') // unstable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+**Correct (destructure early):**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton({ onSave }) {
+  const { push } = useRouter()
+
+  // good: react-compiler will key on push and onSave
+  const handlePress = () => {
+    onSave()
+    push('/success') // stable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```

package/.agents/skills/vercel-react-native-skills/rules/react-compiler-reanimated-shared-values.md

@@ -0,0 +1,48 @@
+---
+title: Use .get() and .set() for Reanimated Shared Values (not .value)
+impact: LOW
+impactDescription: required for React Compiler compatibility
+tags: reanimated, react-compiler, shared-values
+---
+
+## Use .get() and .set() for Shared Values with React Compiler
+
+With React Compiler enabled, use `.get()` and `.set()` instead of reading or
+writing `.value` directly on Reanimated shared values. The compiler can't track
+property access—explicit methods ensure correct behavior.
+
+**Incorrect (breaks with React Compiler):**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.value = count.value + 1 // opts out of react compiler
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.value}`} />
+}
+```
+
+**Correct (React Compiler compatible):**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.set(count.get() + 1)
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.get()}`} />
+}
+```
+
+See the
+[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)
+for more.

package/.agents/skills/vercel-react-native-skills/rules/react-state-dispatcher.md

@@ -0,0 +1,91 @@
+---
+title: useState Dispatch updaters for State That Depends on Current Value
+impact: MEDIUM
+impactDescription: avoids stale closures, prevents unnecessary re-renders
+tags: state, hooks, useState, callbacks
+---
+
+## Use Dispatch Updaters for State That Depends on Current Value
+
+When the next state depends on the current state, use a dispatch updater
+(`setState(prev => ...)`) instead of reading the state variable directly in a
+callback. This avoids stale closures and ensures you're comparing against the
+latest value.
+
+**Incorrect (reads state directly):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  // size may be stale in this closure
+  if (size?.width !== width || size?.height !== height) {
+    setSize({ width, height })
+  }
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => {
+    if (prev?.width === width && prev?.height === height) return prev
+    return { width, height }
+  })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+re-render.
+
+**Incorrect (unnecessary comparison for primitive state):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct (sets primitive state directly):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+dispatch updater.
+
+**Incorrect (reads state directly from the callback):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount(count + 1)
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount((prev) => prev + 1)
+}
+```