@ranimontagna/agent-toolkit 0.1.5 → 0.1.6

package/skills/frontend/react-native/react-native-expert/references/project-structure.md

@@ -0,0 +1,171 @@
+# Project Structure
+
+## Expo Router Structure
+
+```
+my-app/
+├── app/                      # File-based routing
+│   ├── _layout.tsx           # Root layout
+│   ├── index.tsx             # Home screen
+│   ├── +not-found.tsx        # 404 screen
+│   ├── (tabs)/               # Tab navigator group
+│   │   ├── _layout.tsx
+│   │   ├── index.tsx
+│   │   ├── search.tsx
+│   │   └── profile.tsx
+│   ├── (auth)/               # Auth screens (no tabs)
+│   │   ├── _layout.tsx
+│   │   ├── login.tsx
+│   │   └── register.tsx
+│   └── [id].tsx              # Dynamic route
+├── components/
+│   ├── ui/                   # Reusable UI components
+│   │   ├── Button.tsx
+│   │   ├── Card.tsx
+│   │   └── Input.tsx
+│   └── features/             # Feature-specific components
+│       ├── ProductCard.tsx
+│       └── UserAvatar.tsx
+├── hooks/
+│   ├── useAuth.ts
+│   ├── useStorage.ts
+│   └── useApi.ts
+├── services/
+│   ├── api.ts                # API client
+│   └── auth.ts               # Auth service
+├── stores/
+│   └── useUserStore.ts       # Zustand stores
+├── constants/
+│   ├── colors.ts
+│   └── layout.ts
+├── types/
+│   └── index.ts
+├── utils/
+│   └── helpers.ts
+├── assets/
+│   ├── images/
+│   └── fonts/
+├── app.json
+├── babel.config.js
+└── tsconfig.json
+```
+
+## app.json Configuration
+
+```json
+{
+  "expo": {
+    "name": "My App",
+    "slug": "my-app",
+    "version": "1.0.0",
+    "scheme": "myapp",
+    "orientation": "portrait",
+    "icon": "./assets/images/icon.png",
+    "splash": {
+      "image": "./assets/images/splash.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#ffffff"
+    },
+    "ios": {
+      "supportsTablet": true,
+      "bundleIdentifier": "com.company.myapp"
+    },
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/images/adaptive-icon.png",
+        "backgroundColor": "#ffffff"
+      },
+      "package": "com.company.myapp"
+    },
+    "plugins": [
+      "expo-router"
+    ],
+    "experiments": {
+      "typedRoutes": true
+    }
+  }
+}
+```
+
+## tsconfig.json
+
+```json
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"],
+      "@/components/*": ["components/*"],
+      "@/hooks/*": ["hooks/*"],
+      "@/services/*": ["services/*"],
+      "@/stores/*": ["stores/*"],
+      "@/types/*": ["types/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
+}
+```
+
+## babel.config.js
+
+```javascript
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: [
+      [
+        'module-resolver',
+        {
+          root: ['.'],
+          alias: {
+            '@': '.',
+            '@/components': './components',
+            '@/hooks': './hooks',
+          },
+        },
+      ],
+      'react-native-reanimated/plugin', // Must be last
+    ],
+  };
+};
+```
+
+## Essential Dependencies
+
+```json
+{
+  "dependencies": {
+    "expo": "~50.0.0",
+    "expo-router": "~3.4.0",
+    "react-native-safe-area-context": "4.8.2",
+    "react-native-screens": "~3.29.0",
+    "@react-navigation/native": "^6.1.0",
+    "react-native-reanimated": "~3.6.0",
+    "react-native-gesture-handler": "~2.14.0",
+    "zustand": "^4.5.0",
+    "@tanstack/react-query": "^5.0.0",
+    "expo-image": "~1.10.0",
+    "react-native-mmkv": "^2.11.0"
+  },
+  "devDependencies": {
+    "@types/react": "~18.2.0",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+## Quick Reference
+
+| Directory | Purpose |
+|-----------|---------|
+| `app/` | File-based routes |
+| `components/ui/` | Reusable UI |
+| `components/features/` | Feature components |
+| `hooks/` | Custom hooks |
+| `services/` | API, auth services |
+| `stores/` | State management |
+| `constants/` | App constants |
+| `types/` | TypeScript types |

package/skills/frontend/react-native/react-native-expert/references/storage-hooks.md

@@ -0,0 +1,173 @@
+# Storage & Hooks
+
+## AsyncStorage
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// Basic operations
+await AsyncStorage.setItem('user', JSON.stringify(user));
+const user = JSON.parse(await AsyncStorage.getItem('user') || 'null');
+await AsyncStorage.removeItem('user');
+await AsyncStorage.clear();
+
+// Multiple items
+await AsyncStorage.multiSet([
+  ['user', JSON.stringify(user)],
+  ['settings', JSON.stringify(settings)],
+]);
+
+const values = await AsyncStorage.multiGet(['user', 'settings']);
+```
+
+## useStorage Hook
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { useState, useEffect, useCallback } from 'react';
+
+function useStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(initialValue);
+  const [loading, setLoading] = useState(true);
+
+  // Load on mount
+  useEffect(() => {
+    AsyncStorage.getItem(key)
+      .then((item) => {
+        if (item !== null) {
+          setValue(JSON.parse(item));
+        }
+      })
+      .finally(() => setLoading(false));
+  }, [key]);
+
+  // Persist changes
+  const setStoredValue = useCallback(
+    async (newValue: T | ((prev: T) => T)) => {
+      const valueToStore =
+        newValue instanceof Function ? newValue(value) : newValue;
+      setValue(valueToStore);
+      await AsyncStorage.setItem(key, JSON.stringify(valueToStore));
+    },
+    [key, value]
+  );
+
+  const removeValue = useCallback(async () => {
+    setValue(initialValue);
+    await AsyncStorage.removeItem(key);
+  }, [key, initialValue]);
+
+  return { value, setValue: setStoredValue, removeValue, loading };
+}
+
+// Usage
+function Settings() {
+  const { value: theme, setValue: setTheme, loading } = useStorage('theme', 'light');
+
+  if (loading) return <Loading />;
+
+  return (
+    <Switch
+      value={theme === 'dark'}
+      onValueChange={(dark) => setTheme(dark ? 'dark' : 'light')}
+    />
+  );
+}
+```
+
+## MMKV (Faster Alternative)
+
+```typescript
+import { MMKV } from 'react-native-mmkv';
+
+const storage = new MMKV();
+
+// Synchronous operations
+storage.set('user.name', 'John');
+const name = storage.getString('user.name');
+
+storage.set('user.age', 25);
+const age = storage.getNumber('user.age');
+
+storage.set('user.premium', true);
+const isPremium = storage.getBoolean('user.premium');
+
+storage.delete('user.name');
+storage.clearAll();
+
+// JSON data
+storage.set('user', JSON.stringify(user));
+const user = JSON.parse(storage.getString('user') || '{}');
+```
+
+## useMMKV Hook
+
+```typescript
+import { useMMKVString, useMMKVNumber, useMMKVBoolean } from 'react-native-mmkv';
+
+function Settings() {
+  const [theme, setTheme] = useMMKVString('theme');
+  const [fontSize, setFontSize] = useMMKVNumber('fontSize');
+  const [notifications, setNotifications] = useMMKVBoolean('notifications');
+
+  return (
+    <>
+      <Switch
+        value={theme === 'dark'}
+        onValueChange={(dark) => setTheme(dark ? 'dark' : 'light')}
+      />
+      <Slider value={fontSize} onValueChange={setFontSize} />
+      <Switch value={notifications} onValueChange={setNotifications} />
+    </>
+  );
+}
+```
+
+## Zustand with MMKV
+
+```typescript
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import { MMKV } from 'react-native-mmkv';
+
+const storage = new MMKV();
+
+const mmkvStorage = {
+  getItem: (name: string) => storage.getString(name) ?? null,
+  setItem: (name: string, value: string) => storage.set(name, value),
+  removeItem: (name: string) => storage.delete(name),
+};
+
+interface SettingsStore {
+  theme: 'light' | 'dark';
+  setTheme: (theme: 'light' | 'dark') => void;
+}
+
+const useSettingsStore = create<SettingsStore>()(
+  persist(
+    (set) => ({
+      theme: 'light',
+      setTheme: (theme) => set({ theme }),
+    }),
+    {
+      name: 'settings-storage',
+      storage: createJSONStorage(() => mmkvStorage),
+    }
+  )
+);
+```
+
+## Quick Reference
+
+| Storage | Speed | Async | Use Case |
+|---------|-------|-------|----------|
+| AsyncStorage | Slow | Yes | Small data, simple apps |
+| MMKV | Fast | No | Large data, frequent access |
+| SecureStore | Medium | Yes | Sensitive data (tokens) |
+
+| Hook | Returns |
+|------|---------|
+| `useStorage()` | { value, setValue, loading } |
+| `useMMKVString()` | [value, setValue] |
+| `useMMKVNumber()` | [value, setValue] |
+| `useMMKVBoolean()` | [value, setValue] |

package/skills/frontend/react-native/react-native-unistyles-v3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacek Pudysz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/frontend/react-native/react-native-unistyles-v3/NOTICE.md

@@ -0,0 +1,11 @@
+# Attribution
+
+This skill is copied from Jacek Pudysz's public `jpudysz/react-native-unistyles` repository.
+
+- Source: https://github.com/jpudysz/react-native-unistyles/tree/main/skills/react-native-unistyles-v3
+- Imported from commit: `8b5e9fd281a81bdfd87d4fe9e6a0b042c84c5c83`
+- Upstream skill name: `react-native-unistyles-v3`
+- License: MIT, as declared by the upstream README and `packages/unistyles/package.json`
+- Copyright: Copyright (c) 2026 Jacek Pudysz
+
+The upstream repository does not include a root `LICENSE` file in the imported commit, so this vendored copy includes the standard MIT license text in `LICENSE` with the upstream author attribution.

package/skills/frontend/react-native/react-native-unistyles-v3/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: react-native-unistyles-v3
+description: Guide for using react-native-unistyles v3. Triggers on unistyles, StyleSheet.create, create stylesheet, add theme, breakpoints, variants, withUnistyles, useUnistyles, ScopedTheme, UnistylesRuntime, responsive styles, media queries, dynamic styles, scoped theme, adaptive theme, setup, config, theming, variants, web features and troubleshooting.
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(npx *)
+---
+
+# React Native Unistyles v3 Skill
+
+You are assisting with React Native Unistyles v3 styling. v3 is a zero-re-render styling library with a C++ core (Nitro Modules) and Babel plugin that processes StyleSheets at build time. It replaces React Native's `StyleSheet` with a reactive, theme-aware, responsive system.
+
+## Prerequisites
+
+- React Native 0.78+ with **New Architecture mandatory** (default from RN 0.83+)
+- React 19+ (enforced at runtime)
+- `react-native-nitro-modules` (native bridge dependency)
+- `react-native-edge-to-edge` (required for Android edge-to-edge insets)
+- Expo SDK 53+ (if using Expo; **not compatible with Expo Go** — requires dev client or prebuild)
+- Xcode 16+ (iOS)
+
+## Workflow
+
+1. **Read user's code first** — understand current setup, imports, and styling approach
+2. **Identify intent** — new setup, add theming, responsive design, fix an issue, etc.
+3. **Apply v3 patterns** — use the correct API from this skill; consult reference files for details
+4. **Verify correctness** — check for critical rule violations (spreading, barrel re-exports, etc.)
+
+## Quick Reference
+
+### StyleSheet.create — 3 overloads
+
+```tsx
+import { StyleSheet } from 'react-native-unistyles'
+
+// 1. Static object compatible with React Native StyleSheet.create
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 16 }
+})
+
+// 2. Theme function (reactive to theme changes, zero re-renders)
+const styles = StyleSheet.create(theme => ({
+  container: { backgroundColor: theme.colors.background }
+}))
+
+// 3. Theme + miniRuntime function (reactive to theme AND device state)
+const styles = StyleSheet.create((theme, rt) => ({
+  container: {
+    backgroundColor: theme.colors.background,
+    paddingTop: rt.insets.top,
+    width: rt.screen.width > 768 ? 500 : rt.screen.width - 32
+  }
+}))
+```
+
+### StyleSheet.configure — one-time setup
+
+```tsx
+StyleSheet.configure({
+  themes: { light: lightTheme, dark: darkTheme },
+  breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
+  settings: {
+    initialTheme: 'light',       // or: () => storage.getString('theme') ?? 'light'
+    // adaptiveThemes: true,     // auto-switch light/dark based on OS (mutually exclusive with initialTheme)
+    // CSSVars: true,            // use CSS custom properties on web
+    // nativeBreakpointsMode: 'pixels' | 'points'
+  }
+})
+```
+
+### Variants
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  button: {
+    variants: {
+      size: {
+        small: { padding: 4 },
+        medium: { padding: 8 },
+        large: { padding: 16 },
+      },
+      color: {
+        primary: { backgroundColor: theme.colors.primary },
+        secondary: { backgroundColor: theme.colors.secondary },
+      }
+    },
+    compoundVariants: [
+      { size: 'large', color: 'primary', styles: { borderWidth: 2 } }
+    ],
+  }
+}))
+
+// In component — call useVariants BEFORE accessing styles
+styles.useVariants({ size: 'large', color: 'primary' })
+return <View style={styles.button} />
+```
+
+### withUnistyles — wrap third-party components (not React Native or Reanimated components)
+
+```tsx
+import { withUnistyles } from 'react-native-unistyles'
+import { Button } from 'some-library'
+
+const UniButton = withUnistyles(Button, (theme, rt) => ({
+  color: theme.colors.primary,
+  size: rt.screen.width > 400 ? 'large' : 'small'
+}))
+
+// Usage: <UniButton title="Press me" />
+```
+
+## Critical Rules
+
+1. **NEVER spread styles** — `{...styles.x}` breaks C++ proxy binding. ALWAYS use array syntax: `[styles.x, styles.y]` or `[styles.x, { marginTop: 10 }]`
+2. **NEVER re-export StyleSheet from barrel files** — the Babel plugin detects `StyleSheet.create` by import source. Re-exporting breaks detection.
+3. **Babel plugin is REQUIRED** — add `['react-native-unistyles/plugin', { root: 'src' }]` to babel.config.js. Without it, styles won't be reactive.
+4. **Import StyleSheet from `react-native-unistyles` only** — it polyfills all RN StyleSheet APIs (`hairlineWidth`, `compose`, `flatten`, `absoluteFill`). Replace all `import { StyleSheet } from 'react-native'`.
+5. **`styles.useVariants()` must be called before accessing variant-dependent styles** — treat it like a React hook (top of component).
+6. **Prefer `StyleSheet.create(theme => ...)` over `useUnistyles()`** — theme functions cause zero re-renders; `useUnistyles()` re-renders on every theme/runtime change.
+7. **`StyleSheet.configure()` must be called before any `StyleSheet.create()`** — typically in your app entry point, before any component renders.
+
+## Decision Trees
+
+### Choosing a styling approach
+
+```
+Need theme/runtime in styles?
+├─ YES → StyleSheet.create((theme, rt) => ...)     [zero re-renders]
+└─ NO  → StyleSheet.create({ ... })                [static styles]
+
+Need theme values as non-style props?
+├─ YES → withUnistyles(Component, (theme, rt) => ({ propName: theme.value }))
+└─ NO  → Pass Unistyles styles via style prop directly
+
+Need theme/runtime in component logic (not just styles)?
+├─ YES → useUnistyles() hook                        [causes re-renders]
+└─ NO  → Use StyleSheet.create with theme function
+```
+
+### Third-party component integration
+
+```
+Does the component accept a `style` prop?
+├─ YES → Pass Unistyles styles directly (Babel auto-processes standard RN views)
+│        If it's a custom native view → add to autoProcessPaths in Babel config
+├─ NO  → Does it accept theme-derived props (color, size, etc.)?
+│        ├─ YES → withUnistyles(Component, (theme, rt) => ({ prop: theme.value }))
+│        └─ NO  → useUnistyles() as fallback
+└─ Component from node_modules not processed?
+   → Add its path to autoProcessPaths or autoProcessImports in Babel plugin config
+```
+
+## Reference Files
+
+- **Setup, installation, Babel plugin, TypeScript, testing, Expo Router**: read [references/setup-guide.md](references/setup-guide.md)
+- **Complete API for every export**: read [references/api-reference.md](references/api-reference.md)
+- **Code patterns: themes, variants, breakpoints, web, SSR, Reanimated**: read [references/styling-patterns.md](references/styling-patterns.md)
+- **withUnistyles, autoProcessPaths, React Compiler, Reanimated, FlatList**: read [references/third-party-integration.md](references/third-party-integration.md)
+- **Troubleshooting from 150+ GitHub issues with solutions**: read [references/common-issues.md](references/common-issues.md)