devskill 2.0.2

package/skills/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)
+}
+```

package/skills/react-native-skills/rules/react-state-fallback.md

@@ -0,0 +1,56 @@
+---
+title: Use fallback state instead of initialState
+impact: MEDIUM
+impactDescription: reactive fallbacks without syncing
+tags: state, hooks, derived-state, props, initialState
+---
+
+## Use fallback state instead of initialState
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+parent or server values. State represents user intent only—`undefined` means
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+source changes, not just on initial render.
+
+**Incorrect (syncs state, loses reactivity):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [enabled, setEnabled] = useState(defaultEnabled)
+  // If fallbackEnabled changes, state is stale
+  // State mixes user intent with default value
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**Correct (state is user intent, reactive fallback):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [_enabled, setEnabled] = useState<boolean | undefined>(undefined)
+  const enabled = _enabled ?? defaultEnabled
+  // undefined = user hasn't touched it, falls back to prop
+  // If defaultEnabled changes, component reflects it
+  // Once user interacts, their choice persists
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**With server data:**
+
+```tsx
+function ProfileForm({ data }: { data: User }) {
+  const [_theme, setTheme] = useState<string | undefined>(undefined)
+  const theme = _theme ?? data.theme
+  // Shows server value until user overrides
+  // Server refetch updates the fallback automatically
+
+  return <ThemePicker value={theme} onChange={setTheme} />
+}
+```

package/skills/react-native-skills/rules/react-state-minimize.md

@@ -0,0 +1,65 @@
+---
+title: Minimize State Variables and Derive Values
+impact: MEDIUM
+impactDescription: fewer re-renders, less state drift
+tags: state, derived-state, hooks, optimization
+---
+
+## Minimize State Variables and Derive Values
+
+Use the fewest state variables possible. If a value can be computed from existing state or props, derive it during render instead of storing it in state. Redundant state causes unnecessary re-renders and can drift out of sync.
+
+**Incorrect (redundant state):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const [total, setTotal] = useState(0)
+  const [itemCount, setItemCount] = useState(0)
+
+  useEffect(() => {
+    setTotal(items.reduce((sum, item) => sum + item.price, 0))
+    setItemCount(items.length)
+  }, [items])
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Correct (derived values):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const total = items.reduce((sum, item) => sum + item.price, 0)
+  const itemCount = items.length
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)

package/skills/react-native-skills/rules/rendering-no-falsy-and.md

@@ -0,0 +1,74 @@
+---
+title: Never Use && with Potentially Falsy Values
+impact: CRITICAL
+impactDescription: prevents production crash
+tags: rendering, conditional, jsx, crash
+---
+
+## Never Use && with Potentially Falsy Values
+
+Never use `{value && <Component />}` when `value` could be an empty string or
+`0`. These are falsy but JSX-renderable—React Native will try to render them as
+text outside a `<Text>` component, causing a hard crash in production.
+
+**Incorrect (crashes if count is 0 or name is ""):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name && <Text>{name}</Text>}
+      {count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct (ternary with null):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name ? <Text>{name}</Text> : null}
+      {count ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+**Correct (explicit boolean coercion):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {!!name && <Text>{name}</Text>}
+      {!!count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+```
+
+**Best (early return):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  if (!name) return null
+
+  return (
+    <View>
+      <Text>{name}</Text>
+      {count > 0 ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+to catch this automatically.

package/skills/react-native-skills/rules/rendering-text-in-text-component.md

@@ -0,0 +1,36 @@
+---
+title: Wrap Strings in Text Components
+impact: CRITICAL
+impactDescription: prevents runtime crash
+tags: rendering, text, core
+---
+
+## Wrap Strings in Text Components
+
+Strings must be rendered inside `<Text>`. React Native crashes if a string is a
+direct child of `<View>`.
+
+**Incorrect (crashes):**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return <View>Hello, {name}!</View>
+}
+// Error: Text strings must be rendered within a <Text> component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return (
+    <View>
+      <Text>Hello, {name}!</Text>
+    </View>
+  )
+}
+```

package/skills/react-native-skills/rules/scroll-position-no-state.md

@@ -0,0 +1,82 @@
+---
+title: Never Track Scroll Position in useState
+impact: HIGH
+impactDescription: prevents render thrashing during scroll
+tags: scroll, performance, reanimated, useRef
+---
+
+## Never Track Scroll Position in useState
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+for animations or a ref for non-reactive tracking.
+
+**Incorrect (useState causes jank):**
+
+```tsx
+import { useState } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const [scrollY, setScrollY] = useState(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+**Correct (Reanimated for animations):**
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedScrollHandler,
+} from 'react-native-reanimated'
+
+function Feed() {
+  const scrollY = useSharedValue(0)
+
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (e) => {
+      scrollY.value = e.contentOffset.y // runs on UI thread, no re-render
+    },
+  })
+
+  return (
+    <Animated.ScrollView
+      onScroll={onScroll}
+      // higher number has better performance, but it fires less often.
+      // unset this if you need higher precision over performance.
+      scrollEventThrottle={16}
+    />
+  )
+}
+```
+
+**Correct (ref for non-reactive tracking):**
+
+```tsx
+import { useRef } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const scrollY = useRef(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```

package/skills/react-native-skills/rules/state-ground-truth.md

@@ -0,0 +1,80 @@
+---
+title: State Must Represent Ground Truth
+impact: HIGH
+impactDescription: cleaner logic, easier debugging, single source of truth
+tags: state, derived-state, reanimated, hooks
+---
+
+## State Must Represent Ground Truth
+
+State variables—both React `useState` and Reanimated shared values—should
+represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
+not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
+visual values from state using computation or interpolation.
+
+**Incorrect (storing the visual output):**
+
+```tsx
+const scale = useSharedValue(1)
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    scale.set(withTiming(0.95))
+  })
+  .onFinalize(() => {
+    scale.set(withTiming(1))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.get() }],
+}))
+```
+
+**Correct (storing the state, deriving the visual):**
+
+```tsx
+const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    pressed.set(withTiming(1))
+  })
+  .onFinalize(() => {
+    pressed.set(withTiming(0))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
+}))
+```
+
+**Why this matters:**
+
+State variables should represent real "state", not necessarily a desired end
+result.
+
+1. **Single source of truth** — The state (`pressed`) describes what's
+   happening; visuals are derived
+2. **Easier to extend** — Adding opacity, rotation, or other effects just
+   requires more interpolations from the same state
+3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
+4. **Reusable logic** — The same `pressed` value can drive multiple visual
+   properties
+
+**Same principle for React state:**
+
+```tsx
+// Incorrect: storing derived values
+const [isExpanded, setIsExpanded] = useState(false)
+const [height, setHeight] = useState(0)
+
+useEffect(() => {
+  setHeight(isExpanded ? 200 : 0)
+}, [isExpanded])
+
+// Correct: derive from state
+const [isExpanded, setIsExpanded] = useState(false)
+const height = isExpanded ? 200 : 0
+```
+
+State is the minimal truth. Everything else is derived.

package/skills/react-native-skills/rules/ui-expo-image.md

@@ -0,0 +1,66 @@
+---
+title: Use expo-image for Optimized Images
+impact: HIGH
+impactDescription: memory efficiency, caching, blurhash placeholders, progressive loading
+tags: images, performance, expo-image, ui
+---
+
+## Use expo-image for Optimized Images
+
+Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.
+
+**Incorrect (React Native Image):**
+
+```tsx
+import { Image } from 'react-native'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**Correct (expo-image):**
+
+```tsx
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**With blurhash placeholder:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}
+  contentFit="cover"
+  transition={200}
+  style={styles.image}
+/>
+```
+
+**With priority and caching:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  priority="high"
+  cachePolicy="memory-disk"
+  style={styles.hero}
+/>
+```
+
+**Key props:**
+
+- `placeholder` — Blurhash or thumbnail while loading
+- `contentFit` — `cover`, `contain`, `fill`, `scale-down`
+- `transition` — Fade-in duration (ms)
+- `priority` — `low`, `normal`, `high`
+- `cachePolicy` — `memory`, `disk`, `memory-disk`, `none`
+- `recyclingKey` — Unique key for list recycling
+
+For cross-platform (web + native), use `SolitoImage` from `solito/image` which uses `expo-image` under the hood.
+
+Reference: [expo-image](https://docs.expo.dev/versions/latest/sdk/image/)

package/skills/react-native-skills/rules/ui-image-gallery.md

@@ -0,0 +1,104 @@
+---
+title: Use Galeria for Image Galleries and Lightbox
+impact: MEDIUM
+impactDescription:
+  native shared element transitions, pinch-to-zoom, pan-to-close
+tags: images, gallery, lightbox, expo-image, ui
+---
+
+## Use Galeria for Image Galleries and Lightbox
+
+For image galleries with lightbox (tap to fullscreen), use `@nandorojo/galeria`.
+It provides native shared element transitions with pinch-to-zoom, double-tap
+zoom, and pan-to-close. Works with any image component including `expo-image`.
+
+**Incorrect (custom modal implementation):**
+
+```tsx
+function ImageGallery({ urls }: { urls: string[] }) {
+  const [selected, setSelected] = useState<string | null>(null)
+
+  return (
+    <>
+      {urls.map((url) => (
+        <Pressable key={url} onPress={() => setSelected(url)}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Pressable>
+      ))}
+      <Modal visible={!!selected} onRequestClose={() => setSelected(null)}>
+        <Image source={{ uri: selected! }} style={styles.fullscreen} />
+      </Modal>
+    </>
+  )
+}
+```
+
+**Correct (Galeria with expo-image):**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+  return (
+    <Galeria urls={urls}>
+      {urls.map((url, index) => (
+        <Galeria.Image index={index} key={url}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Galeria.Image>
+      ))}
+    </Galeria>
+  )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return (
+    <Galeria urls={[url]}>
+      <Galeria.Image>
+        <Image source={{ uri: url }} style={styles.avatar} />
+      </Galeria.Image>
+    </Galeria>
+  )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+<Galeria urls={highResUrls}>
+  {lowResUrls.map((url, index) => (
+    <Galeria.Image index={index} key={url}>
+      <Image source={{ uri: url }} style={styles.thumbnail} />
+    </Galeria.Image>
+  ))}
+</Galeria>
+```
+
+**With FlashList:**
+
+```tsx
+<Galeria urls={urls}>
+  <FlashList
+    data={urls}
+    renderItem={({ item, index }) => (
+      <Galeria.Image index={index}>
+        <Image source={{ uri: item }} style={styles.thumbnail} />
+      </Galeria.Image>
+    )}
+    numColumns={3}
+    estimatedItemSize={100}
+  />
+</Galeria>
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+component.
+
+Reference: [Galeria](https://github.com/nandorojo/galeria)