@ivannxbt/ai-config 0.1.0

package/.gemini/antigravity/skills/react-native-best-practices/references/js-animations-reanimated.md

@@ -0,0 +1,254 @@
+---
+title: High-Performance Animations
+impact: MEDIUM
+tags: reanimated, animations, worklets, ui-thread
+---
+
+# Skill: High-Performance Animations
+
+Use React Native Reanimated for smooth 60+ FPS animations.
+
+## Quick Pattern
+
+**Incorrect (JS thread - blocks on heavy work):**
+
+```jsx
+const opacity = useRef(new Animated.Value(0)).current;
+Animated.timing(opacity, { toValue: 1 }).start();
+```
+
+**Correct (UI thread - smooth even during JS work):**
+
+```jsx
+const opacity = useSharedValue(0);
+const style = useAnimatedStyle(() => ({ opacity: opacity.value }));
+opacity.value = withTiming(1);
+```
+
+## When to Use
+
+- Animations drop frames or feel janky
+- UI freezes during animations
+- Need gesture-driven animations
+- Want animations to run during heavy JS work
+
+## Prerequisites
+
+- `react-native-reanimated` (v4+) and `react-native-worklets` installed
+
+```bash
+npm install react-native-reanimated react-native-worklets
+```
+
+Add to `babel.config.js`:
+
+```javascript
+module.exports = {
+  plugins: ['react-native-worklets/plugin'],  // Must be last
+};
+```
+
+> **Note**: Reanimated 4 requires React Native's **New Architecture** (Fabric + TurboModules). The Legacy Architecture is no longer supported. If upgrading from v3, see the migration notes at the end of this document.
+
+## Key Concepts
+
+### Main Thread vs JS Thread
+
+- **Main/UI Thread**: Handles native rendering (60+ FPS target)
+- **JS Thread**: Runs React and your JavaScript
+
+**Problem**: Heavy JS work blocks animations running on JS thread.
+
+**Solution**: Run animations on UI thread with Reanimated worklets.
+
+## Step-by-Step Instructions
+
+### 1. Basic Animated Style (UI Thread)
+
+```jsx
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming
+} from 'react-native-reanimated';
+
+const FadeInView = () => {
+  const opacity = useSharedValue(0);
+
+  // This runs on UI thread - won't be blocked by JS
+  const animatedStyle = useAnimatedStyle(() => {
+    return { opacity: opacity.value };
+  });
+
+  useEffect(() => {
+    opacity.value = withTiming(1, { duration: 500 });
+  }, []);
+
+  return <Animated.View style={[styles.box, animatedStyle]} />;
+};
+```
+
+### 2. Run Code on UI Thread with `scheduleOnUI`
+
+```jsx
+import { scheduleOnUI } from 'react-native-worklets';
+
+const triggerAnimation = () => {
+  scheduleOnUI(() => {
+    'worklet';
+    console.log('Running on UI thread');
+    // Direct UI manipulations here
+  });
+};
+```
+
+### 3. Call JS from UI Thread with `scheduleOnRN`
+
+```jsx
+import { scheduleOnRN } from 'react-native-worklets';
+
+// Regular JS function
+const trackAnalytics = (value) => {
+  analytics.track('animation_complete', { value });
+};
+
+const AnimatedComponent = () => {
+  const progress = useSharedValue(0);
+
+  const animatedStyle = useAnimatedStyle(() => {
+    // When animation completes, call JS function
+    if (progress.value === 1) {
+      scheduleOnRN(trackAnalytics, progress.value);
+    }
+    return { opacity: progress.value };
+  });
+
+  return <Animated.View style={animatedStyle} />;
+};
+```
+
+### 4. Animation with Callback
+
+```jsx
+import { scheduleOnRN } from 'react-native-worklets';
+
+const AnimatedButton = () => {
+  const scale = useSharedValue(1);
+
+  const onComplete = () => {
+    console.log('Animation finished!');
+  };
+
+  const handlePress = () => {
+    scale.value = withTiming(
+      1.2,
+      { duration: 200 },
+      (finished) => {
+        if (finished) {
+          scheduleOnRN(onComplete);
+        }
+      }
+    );
+  };
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }));
+
+  return (
+    <Pressable onPress={handlePress}>
+      <Animated.View style={[styles.button, animatedStyle]}>
+        <Text>Press Me</Text>
+      </Animated.View>
+    </Pressable>
+  );
+};
+```
+
+## When to Use What
+
+| Thread | Best For |
+|--------|----------|
+| **UI Thread** (worklets) | Visual animations, transforms, gestures |
+| **JS Thread** | State updates, data processing, API calls |
+
+| Hook/API | Use Case |
+|----------|----------|
+| `useAnimatedStyle` | Animated styles (auto UI thread) |
+| `scheduleOnUI` | Manual UI thread execution (from `react-native-worklets`) |
+| `scheduleOnRN` | Call JS functions from worklets (from `react-native-worklets`) |
+| `useTransition` | Alternative for React state-driven delays |
+
+## Common Pitfalls
+
+- **Accessing React state in worklets**: Use `useSharedValue` instead of `useState` for animated values
+- **Not using Animated components**: Must use `Animated.View`, `Animated.Text`, etc.
+- **Heavy computation in useAnimatedStyle**: Keep worklets fast
+- **Forgetting 'worklet' directive**: Required for inline worklet functions
+
+```jsx
+// BAD: Regular function in useAnimatedStyle
+const style = useAnimatedStyle(() => {
+  heavyComputation();  // Blocks UI thread!
+  return { opacity: 1 };
+});
+
+// GOOD: Keep worklets fast
+const style = useAnimatedStyle(() => {
+  return { opacity: opacity.value };  // Just read value
+});
+```
+
+## Migrating from Reanimated 3.x to 4.x
+
+If you're upgrading from Reanimated 3.x, here are the key changes.
+
+> **Can't upgrade to v4?** If your project is blocked from migrating to New Architecture (e.g., incompatible native libraries, complex native code, or timeline constraints), keep using existing APIs and leverage native drivers where applicable. Avoid introducing legacy Reanimated 3.x or older to reduce future migration complexity.
+
+### Breaking Changes
+
+| Old API (v3) | New API (v4) | Package |
+|--------------|--------------|---------|
+| `runOnUI(() => {...})()` | `scheduleOnUI(() => {...})` | `react-native-worklets` |
+| `runOnJS(fn)(args)` | `scheduleOnRN(fn, args)` | `react-native-worklets` |
+| `executeOnUIRuntimeSync` | `runOnUISync` | `react-native-worklets` |
+| `runOnRuntime` | `scheduleOnRuntime` | `react-native-worklets` |
+| `useScrollViewOffset` | `useScrollOffset` | `react-native-reanimated` |
+| `useWorkletCallback` | Use `useCallback` with `'worklet';` directive | React |
+
+### Removed APIs
+
+- `useAnimatedGestureHandler` - Migrate to the Gesture API from `react-native-gesture-handler` v2+
+- `addWhitelistedNativeProps` / `addWhitelistedUIProps` - No longer needed
+- `combineTransition` - Use `EntryExitTransition.entering(...).exiting(...)` instead
+
+### withSpring Changes
+
+```jsx
+// Before (v3)
+withSpring(value, {
+  restDisplacementThreshold: 0.01,
+  restSpeedThreshold: 0.01,
+  duration: 300,
+});
+
+// After (v4)
+withSpring(value, {
+  energyThreshold: 0.01,  // Replaces both threshold parameters
+  duration: 200,          // Duration is now "perceptual" (~1.5x actual time)
+});
+```
+
+### Migration Checklist
+
+1. **Enable New Architecture** - Reanimated 4 only supports Fabric + TurboModules
+2. **Install `react-native-worklets`** - Required new dependency
+3. **Update Babel plugin** - Change `'react-native-reanimated/plugin'` to `'react-native-worklets/plugin'`
+4. **Update imports** - Move worklet functions to `react-native-worklets`
+5. **Update API calls** - New functions take callback + args directly (not curried)
+6. **Rebuild native apps** - Required after adding `react-native-worklets`
+
+## Related Skills
+
+- [js-measure-fps.md](./js-measure-fps.md) - Verify animation frame rate
+- [js-concurrent-react.md](./js-concurrent-react.md) - React-level deferral with useTransition

package/.gemini/antigravity/skills/react-native-best-practices/references/js-atomic-state.md

@@ -0,0 +1,245 @@
+---
+title: Atomic State Management
+impact: HIGH
+tags: state, jotai, zustand, re-renders, context
+---
+
+# Skill: Atomic State Management
+
+Use atomic state libraries (Jotai, Zustand) to reduce unnecessary re-renders without manual memoization.
+
+## Quick Pattern
+
+**Before (Context - all consumers re-render):**
+
+```jsx
+const { filter, todos } = useContext(TodoContext);
+// Re-renders when ANY state changes
+```
+
+**After (Zustand - only subscribed state):**
+
+```jsx
+const filter = useTodoStore((s) => s.filter);
+// Only re-renders when filter changes
+```
+
+## When to Use
+
+- Global state changes cause widespread re-renders
+- Using React Context for app state
+- Components re-render even when their data hasn't changed
+- Want to avoid manual `useMemo`/`useCallback` everywhere
+- Not ready to adopt React Compiler
+
+## Prerequisites
+
+- State management library: `jotai` or `zustand`
+
+```bash
+npm install jotai
+# or
+npm install zustand
+```
+
+## Problem Description
+
+With traditional React state or Context:
+
+```jsx
+// When filter OR todos change, EVERYTHING re-renders
+const App = () => {
+  const [filter, setFilter] = useState('all');
+  const [todos, setTodos] = useState([]);
+  
+  return (
+    <>
+      <FilterMenu filter={filter} setFilter={setFilter} />
+      <TodoList todos={todos} filter={filter} setTodos={setTodos} />
+    </>
+  );
+};
+```
+
+Changing a todo re-renders FilterMenu even though it doesn't use todos.
+
+## Step-by-Step Instructions
+
+### Using Jotai
+
+#### 1. Define Atoms
+
+```jsx
+import { atom } from 'jotai';
+
+// Each atom is an independent piece of state
+const filterAtom = atom('all');
+const todosAtom = atom([]);
+
+// Derived atom (computed value)
+const filteredTodosAtom = atom((get) => {
+  const filter = get(filterAtom);
+  const todos = get(todosAtom);
+  
+  if (filter === 'active') return todos.filter(t => !t.completed);
+  if (filter === 'completed') return todos.filter(t => t.completed);
+  return todos;
+});
+```
+
+#### 2. Use Atoms in Components
+
+```jsx
+import { useAtom, useAtomValue, useSetAtom } from 'jotai';
+
+// Only re-renders when filterAtom changes
+const FilterMenu = () => {
+  const [filter, setFilter] = useAtom(filterAtom);
+  
+  return (
+    <View>
+      {['all', 'active', 'completed'].map((f) => (
+        <Pressable key={f} onPress={() => setFilter(f)}>
+          <Text style={filter === f ? styles.active : null}>{f}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+};
+
+// Only re-renders when todosAtom changes
+const TodoItem = ({ id }) => {
+  const setTodos = useSetAtom(todosAtom);  // Only setter, no re-render on read
+  
+  const toggleTodo = () => {
+    setTodos((prev) => 
+      prev.map((t) => t.id === id ? { ...t, completed: !t.completed } : t)
+    );
+  };
+  
+  return <Pressable onPress={toggleTodo}>...</Pressable>;
+};
+```
+
+### Using Zustand
+
+#### 1. Create Store
+
+```jsx
+import { create } from 'zustand';
+
+const useTodoStore = create((set, get) => ({
+  filter: 'all',
+  todos: [],
+  
+  setFilter: (filter) => set({ filter }),
+  
+  toggleTodo: (id) => set((state) => ({
+    todos: state.todos.map((t) =>
+      t.id === id ? { ...t, completed: !t.completed } : t
+    ),
+  })),
+  
+  // Selector for derived state
+  getFilteredTodos: () => {
+    const { filter, todos } = get();
+    if (filter === 'active') return todos.filter(t => !t.completed);
+    if (filter === 'completed') return todos.filter(t => t.completed);
+    return todos;
+  },
+}));
+```
+
+#### 2. Use Selectors
+
+```jsx
+// Only re-renders when filter changes
+const FilterMenu = () => {
+  const filter = useTodoStore((state) => state.filter);
+  const setFilter = useTodoStore((state) => state.setFilter);
+  
+  return (
+    <View>
+      {['all', 'active', 'completed'].map((f) => (
+        <Pressable key={f} onPress={() => setFilter(f)}>
+          <Text>{f}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+};
+
+// Only re-renders when todos change
+const TodoList = () => {
+  const todos = useTodoStore((state) => state.todos);
+  return todos.map((todo) => <TodoItem key={todo.id} {...todo} />);
+};
+```
+
+## Code Examples
+
+### Before: Context-Based (Many Re-renders)
+
+```jsx
+const TodoContext = createContext();
+
+const TodoProvider = ({ children }) => {
+  const [state, setState] = useState({ filter: 'all', todos: [] });
+  return (
+    <TodoContext.Provider value={{ state, setState }}>
+      {children}
+    </TodoContext.Provider>
+  );
+};
+
+// Every component using this context re-renders on ANY state change
+const FilterMenu = () => {
+  const { state, setState } = useContext(TodoContext);
+  // Re-renders when todos change too!
+};
+```
+
+### After: Atomic (Targeted Re-renders)
+
+```jsx
+// Jotai version - only affected components re-render
+const filterAtom = atom('all');
+const todosAtom = atom([]);
+
+const FilterMenu = () => {
+  const [filter, setFilter] = useAtom(filterAtom);
+  // Only re-renders when filter changes
+};
+
+const TodoList = () => {
+  const todos = useAtomValue(todosAtom);
+  // Only re-renders when todos change
+};
+```
+
+## Comparison
+
+| Feature | Context | Jotai | Zustand |
+|---------|---------|-------|---------|
+| Re-render scope | All consumers | Atom subscribers | Selector subscribers |
+| Derived state | Manual | Built-in atoms | Selectors |
+| DevTools | React DevTools | Jotai DevTools | Zustand DevTools |
+| Bundle size | 0 KB | ~3 KB | ~2 KB |
+| Learning curve | Low | Medium | Low |
+
+## When to Use Which
+
+- **Jotai**: Fine-grained state, many small atoms, derived/async atoms
+- **Zustand**: Simpler mental model, single store, familiar Redux-like pattern
+- **React Compiler**: If available, may eliminate need for these libraries
+
+## Common Pitfalls
+
+- **Over-atomizing**: Don't create an atom for every variable. Group related state.
+- **Missing selectors in Zustand**: Always use selectors to prevent unnecessary re-renders.
+- **Derived state without memoization**: Use derived atoms (Jotai) or memoized selectors.
+
+## Related Skills
+
+- [js-react-compiler.md](./js-react-compiler.md) - Automatic memoization alternative
+- [js-profile-react.md](./js-profile-react.md) - Verify re-render reduction