ginskill-init 2.7.0

package/skills/react-native-expo/references/navigation.md

@@ -0,0 +1,199 @@
+# Navigation — Expo Router v5
+
+## Route Structure
+
+```
+src/app/
+  _layout.tsx              # Root: providers + auth guards (Stack.Protected)
+  +native-intent.tsx       # Native deep link handler
+  (auth)/
+    _layout.tsx            # Auth stack (fade animation, no gesture back)
+    login.tsx              # Apple, Google, email OAuth
+  (onboarding)/
+    _layout.tsx            # Onboarding stack (slide_from_right, no gesture back)
+    select-language.tsx    # Language selection
+    step1-7.tsx            # 7-step setup flow
+  (main)/
+    _layout.tsx            # Main stack: registers all push/modal screens
+    index.tsx              # Main entry redirect
+    (tabs)/                # 4 tabs: Home, Wardrobe, Stylist, Profile
+      _layout.tsx          # Dual-mode: NativeTabs (iOS 26+ Liquid Glass) or ClassicTabs
+      home/
+      stylist/
+      profile/
+      (wardrobe)/          # Items + outfits sub-tabs
+    (wardrobe)/            # Push screens: item-detail, overview, upload-animation
+    (outfits)/             # Modals: maker (slide_from_bottom), save-modal (transparentModal)
+    (styling)/             # Modals: tryon, feedback (slide_from_bottom), about-stylist (push)
+    (discover)/            # Transparent modal: product-modal
+    (calendar)/            # Outfit calendar screens
+    (shared)/              # Shared modals: earn-credits, feedback-modal, referral, sty-history
+    notifications/
+  (global)/                # Transparent modals accessible from anywhere: loading, product-modal
+```
+
+## Route-Screen Delegation Pattern
+
+Route files in `src/app/` are **thin delegators** (under 10 lines). Screen logic lives in `src/screens/` mirroring the same path:
+
+```typescript
+// src/app/(main)/(tabs)/home/index.tsx — THIN DELEGATOR
+import HomeScreen from "@/screens/(main)/(tabs)/home"
+export default function HomeRoute() {
+  return <HomeScreen />
+}
+```
+
+Some route files wrap screens with feature dialogs:
+
+```typescript
+// src/app/(main)/(wardrobe)/item-detail.tsx
+import ClosetItemDetailScreen from "@/screens/(main)/(wardrobe)/item-detail"
+import { ItemDialogs } from "@/features/item/_ui/item-dialogs"
+import { useLocalSearchParams } from "expo-router"
+
+export default function ClosetItemDetailRoute() {
+  const { item_id } = useLocalSearchParams<{ item_id: string }>()
+  return (
+    <>
+      <ClosetItemDetailScreen />
+      <ItemDialogs item_id={item_id} />
+    </>
+  )
+}
+```
+
+Screen folders contain `index.tsx` plus `_components/` for screen-specific sub-components:
+
+```
+src/screens/(main)/(tabs)/home/
+  index.tsx
+  _components/
+    compact-header.tsx
+    weather-row.tsx
+    todays-picks-section.tsx
+    ai-stylist-row.tsx
+```
+
+## Auth Flow
+
+Root `_layout.tsx` uses `Stack.Protected guard={condition}` to gate access:
+
+```typescript
+const isLoggedIn = isAuthenticated && !!user
+const needsOnboarding = isLoggedIn && !user?.is_onboarding_completed
+const isAppReady = !isLoading && isAppInitialized && isOtaReady
+
+<Stack>
+  <Stack.Protected guard={!isLoggedIn}>
+    <Stack.Screen name="(auth)" />
+  </Stack.Protected>
+  <Stack.Protected guard={isLoggedIn && needsOnboarding}>
+    <Stack.Screen name="(onboarding)" />
+  </Stack.Protected>
+  <Stack.Protected guard={isLoggedIn && !needsOnboarding}>
+    <Stack.Screen name="(main)" />
+  </Stack.Protected>
+  <Stack.Screen name="(global)" />
+</Stack>
+```
+
+Global overlays in root layout: `NetworkErrorOverlay`, `ForceUpdateOverlay`, `DailyCheckInSheet`, `QuotaExceededDialog`, `RemoteDialogContainer`.
+
+## Tab Layout (Dual-Mode)
+
+```typescript
+// iOS 26+ uses NativeTabs (Liquid Glass native zoom + slide animations)
+// Older iOS + Android uses ClassicTabs (custom tab bar)
+const isLiquidGlass = Platform.OS === "ios" && parseInt(Platform.Version, 10) >= 26
+
+// Tabs: home, (wardrobe), stylist, profile
+// Tab config loaded from @/screens/(main)/(tabs)/_constants/tabs.const
+```
+
+## Navigation Patterns
+
+### Typed Routes
+
+```typescript
+import { router } from "expo-router"
+import { ROUTES } from "@/shared/constant/route"
+
+// Navigate with typed routes
+router.push(ROUTES.ITEM_DETAIL.path)
+router.push({ pathname: "/(main)/(wardrobe)/item-detail", params: { item_id: "123" } })
+router.back()
+router.replace(ROUTES.LOGIN.path)
+router.setParams({ date: newDate })  // Update current route params
+```
+
+### Route Params
+
+```typescript
+// Extract params in route/screen files
+const { item_id } = useLocalSearchParams<{ item_id: string }>()
+
+// Complex params (JSON-encoded)
+const { productData } = useLocalSearchParams()
+const product = productData ? JSON.parse(productData) : null
+```
+
+### Modal Presentation
+
+```typescript
+<Stack.Screen
+  name="(outfits)/maker"
+  options={{ presentation: "modal", animation: "slide_from_bottom", headerShown: false }}
+/>
+<Stack.Screen
+  name="(discover)/product-modal"
+  options={{ presentation: "transparentModal", animation: "fade" }}
+/>
+```
+
+## Creating a New Screen
+
+1. Create screen: `src/screens/(main)/(section)/screen-name/index.tsx`
+2. Add sub-components: `src/screens/(main)/(section)/screen-name/_components/`
+3. Create thin route: `src/app/(main)/(section)/screen-name.tsx`
+4. Register in parent `_layout.tsx` Stack
+5. Add to `ROUTES` constant in `src/shared/constant/route.ts`
+
+## Screen Component Pattern
+
+```typescript
+export default function HomeScreen() {
+  const { t } = useTranslation()
+  const { top } = useSafeAreaInsets()
+  const queryClient = useQueryClient()
+
+  const onRefresh = useCallback(async () => {
+    await queryClient.invalidateQueries()
+  }, [queryClient])
+
+  useFocusEffect(useCallback(() => {
+    logEvent("home_viewed")
+  }, []))
+
+  return (
+    <View style={styles.screen}>
+      <ScrollView>{/* Content */}</ScrollView>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, backgroundColor: Theme.color.backgroundSubtle },
+})
+```
+
+## Best Practices
+
+- Keep route files under 10 lines — delegate to screens
+- Use route groups `()` for organization without affecting URL
+- Prefer `router.push()` over `<Link>` for programmatic navigation
+- Use `useLocalSearchParams()` for type-safe params
+- Use `useFocusEffect()` for screen focus side effects (analytics, refresh)
+- Avoid nesting more than 3 levels of stack navigators
+- Use `(shared)` group for screens accessible from multiple tabs
+- Feature dialogs live alongside route files, not inside screens

package/skills/react-native-expo/references/performance.md

@@ -0,0 +1,229 @@
+# Performance — Animations, Lists, and Optimization
+
+## React Native Reanimated v4
+
+Runs animations on the UI thread for 60fps regardless of JS thread activity. Uses `react-native-worklets` (separate package in v4).
+
+### Shared Values & Animated Styles
+
+```typescript
+import Animated, {
+  useSharedValue, useAnimatedStyle,
+  withTiming, withSpring, withDelay, withSequence, withRepeat,
+  interpolate, Extrapolation, runOnJS,
+} from "react-native-reanimated"
+
+const Component = () => {
+  const opacity = useSharedValue(0)
+  const translateY = useSharedValue(50)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{ translateY: translateY.value }],
+  }))
+
+  const show = () => {
+    opacity.value = withTiming(1, { duration: 300 })
+    translateY.value = withSpring(0, { damping: 15, stiffness: 150 })
+  }
+
+  return <Animated.View style={animatedStyle} />
+}
+```
+
+### Animation Functions
+
+| Function | Use Case |
+|----------|----------|
+| `withTiming(toValue, { duration })` | Duration-based, predictable |
+| `withSpring(toValue, { damping, stiffness })` | Physics-based, natural |
+| `withDelay(ms, animation)` | Delayed start |
+| `withSequence(anim1, anim2, ...)` | Sequential |
+| `withRepeat(animation, count, reverse)` | Looping |
+| `interpolate(value, inputRange, outputRange)` | Value mapping |
+
+### Spring Presets
+
+```typescript
+const snappy = { damping: 15, stiffness: 200, mass: 0.8 }   // Buttons, toggles
+const gentle = { damping: 20, stiffness: 100, mass: 1 }      // Modals, panels
+const bouncy = { damping: 8, stiffness: 150, mass: 0.5 }     // Playful elements
+```
+
+### Gesture Handler Integration
+
+```typescript
+import { Gesture, GestureDetector } from "react-native-gesture-handler"
+
+const DraggableCard = () => {
+  const translateX = useSharedValue(0)
+  const translateY = useSharedValue(0)
+
+  const gesture = Gesture.Pan()
+    .onUpdate((e) => {
+      translateX.value = e.translationX
+      translateY.value = e.translationY
+    })
+    .onEnd(() => {
+      translateX.value = withSpring(0)
+      translateY.value = withSpring(0)
+    })
+
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateX: translateX.value }, { translateY: translateY.value }],
+  }))
+
+  return (
+    <GestureDetector gesture={gesture}>
+      <Animated.View style={style}>{/* content */}</Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+### Entering/Exiting Layout Animations
+
+```typescript
+import Animated, { FadeIn, FadeOut, SlideInRight, SlideOutLeft } from "react-native-reanimated"
+
+<Animated.View entering={FadeIn.duration(300)} exiting={FadeOut.duration(200)}>
+  {/* content */}
+</Animated.View>
+
+// Staggered list items
+<Animated.View entering={FadeIn.delay(index * 50).duration(300)}>
+  {/* item */}
+</Animated.View>
+```
+
+### Performance Limits
+
+- Max **100 animated components** on low-end Android
+- Max **500 animated components** on iOS
+- Never read shared values on JS thread — only in worklets/useAnimatedStyle
+- For complex visuals, use `react-native-skia` instead of many animated components
+
+## FlashList v2 — High-Performance Lists
+
+FlashList v2 is New Architecture only, uses recycling for near-native perf. **Always use FlashList, never FlatList.**
+
+### Basic Usage
+
+```typescript
+import { FlashList } from "@shopify/flash-list"
+
+<FlashList
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
+  estimatedItemSize={120}        // Required: approximate item height
+  keyExtractor={(item) => item._id}
+/>
+```
+
+### Optimized Pattern
+
+```typescript
+const renderItem = useCallback(({ item }: { item: ItemRes }) => (
+  <MemoizedItemCard item={item} />
+), [])
+
+const MemoizedItemCard = React.memo(({ item }: { item: ItemRes }) => (
+  <View><Typography variant="b2">{item.name}</Typography></View>
+))
+
+<FlashList
+  data={items}
+  renderItem={renderItem}
+  estimatedItemSize={120}
+  keyExtractor={(item) => item._id}
+  drawDistance={250}                    // Pre-render distance
+  onEndReached={onEndReached}          // Infinite scroll
+  onEndReachedThreshold={0.5}
+  numColumns={2}                        // Grid layout
+  getItemType={(item) => item.type}    // CRITICAL for mixed item types
+  ListFooterComponent={isFetchingNextPage ? <ActivityIndicator /> : null}
+  ListEmptyComponent={<EmptyState />}
+/>
+```
+
+### Key Rules
+
+1. **Never use `key` prop** inside item components — defeats recycling
+2. **Use `getItemType`** for heterogeneous lists
+3. **Always provide `estimatedItemSize`** — measure one item
+4. **Profile in release mode** — dev mode perf is misleading
+5. **Memoize `renderItem`** with `useCallback`
+6. **Memoize item components** with `React.memo`
+
+## expo-image — Optimized Image Loading
+
+```typescript
+import { Image } from "expo-image"
+
+<Image
+  source={{ uri: imageUrl }}
+  style={{ width: 100, height: 100 }}
+  contentFit="cover"
+  transition={200}              // Fade-in ms
+  cachePolicy="memory-disk"     // Default, recommended
+  placeholder={blurhash}        // Optional blurhash
+  recyclingKey={item._id}       // For list recycling
+/>
+
+// Prefetch
+await Image.prefetch(urls)
+// Clear cache
+await Image.clearDiskCache()
+```
+
+| Cache Policy | Description |
+|-------------|-------------|
+| `memory-disk` | Default. Memory + disk |
+| `memory` | Memory only |
+| `disk` | Disk only |
+| `none` | No caching |
+
+## General Performance Best Practices
+
+### Component Optimization
+
+```typescript
+// Memoize expensive components
+const ExpensiveChild = React.memo(({ data }) => { /* ... */ })
+
+// Memoize callbacks passed as props
+const handlePress = useCallback(() => { /* ... */ }, [dep])
+
+// Memoize computed values
+const filtered = useMemo(() => items.filter(i => i.category === selected), [items, selected])
+```
+
+### Avoid Common Pitfalls
+
+```typescript
+// BAD: Inline styles (new object every render)
+<View style={{ padding: 16, backgroundColor: "#fff" }}>
+
+// GOOD: StyleSheet.create (cached)
+const styles = StyleSheet.create({
+  container: { padding: Spacing.lg, backgroundColor: Theme.color.backgroundElevated },
+})
+
+// BAD: Arrow in render (new reference)
+<Button onPress={() => handlePress(item._id)} />
+
+// GOOD: Memoized callback
+const onPress = useCallback(() => handlePress(item._id), [item._id])
+```
+
+### Metro Optimization
+
+- `inlineRequires: true` in `metro.config.js` — defers module loading, improves cold start
+- `.lottie` and `.cjs` added as asset/source extensions
+- SVG support via `react-native-svg-transformer`
+
+### Platform-Specific
+
+- **Shimmer**: `shimmer.ios.tsx` / `shimmer.android.tsx` (platform file extensions)
+- **Android**: `removeClippedSubviews={true}` on large lists
+- **Lottie**: Keep files under 100KB; for complex animations use Skia

package/skills/react-native-expo/references/platform-services.md

@@ -0,0 +1,179 @@
+# Platform Services — Auth, Push, Deep Links, i18n, Analytics
+
+## Authentication
+
+### OAuth Providers
+
+- **Apple**: `expo-apple-authentication` → `src/features/auth/sign-in-with-apple.service.ts`
+- **Google**: `@react-native-google-signin/google-signin` → `src/features/auth/sign-in-with-google.service.ts`
+- **Facebook**: `react-native-fbsdk-next` (auto-initialized via app.config.ts)
+- **Sign out**: `src/features/auth/sign-out.service.ts`
+
+### Auth Bootstrap (`src/shared/hooks/use-auth-init.ts`)
+
+Runs once in root layout:
+1. Wait for Zustand hydration (`isHydrated`)
+2. Validate token integrity (`validateTokenIntegrity()`)
+3. If valid → `setAuthenticated(true)`, else → `logout()`
+4. Fetch user profile → set `useUserStore`
+5. Init Adapty (subscriptions) + sync Adapty user ID
+6. Sync Sty balance + retry pending verifications
+7. **15-second timeout guard** → force sign-out if user never loads
+
+Error handling: Network errors keep auth state; 401/404 triggers `handleAuthFailure()` → sign out.
+
+### Token Management
+
+```typescript
+import { storeTokens, getAccessToken, clearTokens, hasValidTokens } from "@/shared/libs/token-storage"
+
+await storeTokens({ accessToken, refreshToken })  // After login
+// Auto-injected by api-client interceptor
+// 401 → auto-refresh (single-flight, max 2 retries) → if fails, sign out
+```
+
+## Push Notifications
+
+```typescript
+import * as Notifications from "expo-notifications"
+import { usePushNotifications } from "@/shared/hooks/use-push-notifications"
+
+// Hook handles: permission request, token registration, notification handlers
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldShowAlert: true, shouldPlaySound: true, shouldSetBadge: true,
+  }),
+})
+```
+
+## Deep Linking
+
+### Branch.io
+
+```typescript
+import branch from "react-native-branch"
+
+branch.subscribe(({ error, params }) => {
+  if (params["+clicked_branch_link"]) {
+    router.push({ pathname: params.screen, params: { id: params.id } })
+  }
+})
+```
+
+### Airbridge
+
+Configured via `airbridge-expo-sdk` plugin in `app.config.ts`. Associated domains for universal links.
+
+### Native Intent
+
+`src/app/+native-intent.tsx` processes incoming URLs.
+
+## Internationalization (i18n)
+
+9 languages via `i18next` + `react-i18next`. Config in `src/features/multi-languages/`.
+
+```typescript
+import { useTranslation } from "react-i18next"
+
+const { t } = useTranslation()
+<Typography variant="b1">{t("home.welcome")}</Typography>
+```
+
+Language stored in MMKV for instant startup access. Locale JSON files in `src/features/multi-languages/locales/`.
+
+## Analytics
+
+### Airbridge (Primary) + Facebook
+
+```typescript
+import { logEvent } from "@/shared/utils/log-event"
+
+logEvent("item_created", { category: "tops", source: "camera" })
+logEvent("outfit_saved", { itemCount: 3 })
+logEvent("subscription_started", { plan: "premium" })
+```
+
+### User Properties
+
+```typescript
+import { setUserProperty } from "@/shared/utils/set-user-property"
+setUserProperty("subscription_tier", "premium")
+```
+
+## Subscriptions — Adapty
+
+```typescript
+import { adapty } from "react-native-adapty"
+// Managed via createAdaptySlice in app-store
+// Paywall presentation, subscription status, receipt validation
+```
+
+### Store Review
+
+```typescript
+import * as StoreReview from "expo-store-review"
+if (await StoreReview.hasAction()) await StoreReview.requestReview()
+```
+
+## Live Activity (iOS)
+
+```typescript
+import { useLiveActivityManager } from "@/shared/live-activity"
+// Start/update/end live activities for long-running tasks (e.g., outfit generation)
+// Uses expo-live-activity with push notification support
+```
+
+## Location
+
+```typescript
+import { useLocation } from "@/features/location"
+// Flow: permission → device location → sync to backend → weather recommendations
+// Services in src/features/location/_services/
+```
+
+## Haptics
+
+```typescript
+import * as Haptics from "expo-haptics"
+Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)    // Buttons
+Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)   // Toggles
+Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success)  // Confirmations
+```
+
+## Clipboard / Linking / Browser
+
+```typescript
+import * as Clipboard from "expo-clipboard"
+import * as WebBrowser from "expo-web-browser"
+import * as Linking from "expo-linking"
+
+await Clipboard.setStringAsync("text")
+await WebBrowser.openBrowserAsync(url)  // In-app browser
+await Linking.openURL(url)              // System browser
+await Linking.openSettings()            // App settings
+```
+
+## Environment Configuration
+
+```
+.env.local    → Development (default)
+.env.staging  → Staging/Preview
+.env.prod     → Production
+```
+
+Key env vars: `EXPO_PUBLIC_API_URL`, `EXPO_PUBLIC_APP_NAME`, `APP_VARIANT=development` (appends `.dev` to bundle IDs), `EXPO_ENV` (controls env file loading).
+
+`app.config.ts` loads env files based on `EXPO_ENV`. Production builds set `SKIP_LOCAL_ENV=1`.
+
+## Logging
+
+```typescript
+import { Logger } from "@/shared/utils/logger"
+
+Logger.info("User signed in", { userId })
+Logger.warn("Slow response", { endpoint, duration })
+Logger.error("Upload failed", { error: err.message })
+// Dev: console with emojis/colors. Prod: errors shipped via clientLogger (batched, with backoff)
+```
+
+Client logger (`src/shared/services/client-logger.service.ts`): max 200 entries queue, batch flush at 20 or every 10s, 429 backoff, connectivity check before flush.