skillstore-cli 1.0.0

package/data/shared/framework/skills/mobile-development/references/mobile-performance.md

@@ -0,0 +1,524 @@
+# Mobile Performance Optimization
+
+## Rendering Performance
+
+### FlatList Optimization (React Native)
+
+```typescript
+<FlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  // Critical performance props:
+  getItemLayout={(_, index) => ({
+    length: ITEM_HEIGHT,
+    offset: ITEM_HEIGHT * index,
+    index,
+  })}
+  maxToRenderPerBatch={10}        // Render 10 items per batch
+  windowSize={5}                  // Render 5 screens worth of content
+  removeClippedSubviews={true}    // Unmount off-screen items (Android)
+  initialNumToRender={10}         // First render shows 10 items
+/>
+```
+
+**Common FlatList mistakes:**
+- Creating new functions/objects inside `renderItem` — extract and memoize
+- Missing `keyExtractor` or using array index as key
+- Not providing `getItemLayout` for fixed-height items
+- Wrapping FlatList in ScrollView (breaks virtualization)
+
+### Memoize Expensive Components
+
+```typescript
+// React Native — memo with custom comparison
+const OrderCard = memo(function OrderCard({ order, onPress }: Props) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>{order.title}</Text>
+      <Text>{order.status}</Text>
+    </Pressable>
+  );
+}, (prev, next) => prev.order.id === next.order.id && prev.order.status === next.order.status);
+
+// Extract renderItem to avoid re-creation
+const renderItem = useCallback(({ item }: { item: Order }) => (
+  <OrderCard order={item} onPress={() => handlePress(item.id)} />
+), [handlePress]);
+```
+
+### Flutter ListView Optimization
+
+```dart
+// Use ListView.builder — NEVER ListView with children for long lists
+ListView.builder(
+  itemCount: items.length,
+  itemBuilder: (context, index) => OrderCard(order: items[index]),
+  // For fixed-height items:
+  itemExtent: 80.0,
+  // Or use prototype:
+  prototypeItem: const OrderCard(order: Order.placeholder()),
+)
+
+// Use const constructors everywhere possible
+class OrderCard extends StatelessWidget {
+  const OrderCard({required this.order});  // const constructor
+  final Order order;
+  // ...
+}
+```
+
+### Image Handling
+
+```typescript
+// React Native — use FastImage for caching
+import FastImage from 'react-native-fast-image';
+
+<FastImage
+  source={{
+    uri: imageUrl,
+    priority: FastImage.priority.normal,
+    cache: FastImage.cacheControl.immutable,
+  }}
+  style={{ width: 100, height: 100 }}
+  resizeMode={FastImage.resizeMode.cover}
+/>
+
+// Preload images for upcoming screens
+FastImage.preload([
+  { uri: 'https://example.com/hero.jpg' },
+  { uri: 'https://example.com/banner.jpg' },
+]);
+```
+
+```dart
+// Flutter — CachedNetworkImage
+CachedNetworkImage(
+  imageUrl: imageUrl,
+  placeholder: (_, __) => const ShimmerPlaceholder(),
+  errorWidget: (_, __, ___) => const Icon(Icons.error),
+  memCacheWidth: 200,  // Decode to smaller resolution
+)
+```
+
+**Image best practices:**
+- Serve images at appropriate resolution (1x, 2x, 3x)
+- Use WebP format when possible (30% smaller than JPEG)
+- Implement progressive loading (blur placeholder → full image)
+- Set `memCacheWidth`/`memCacheHeight` to decoded size, not original
+
+## Memory Management
+
+### Avoiding Leaks
+
+The top 3 causes of memory leaks in mobile apps:
+
+**1. Unremoved listeners and subscriptions**
+```typescript
+// BAD — listener never removed
+useEffect(() => {
+  socket.on('orderUpdate', handleUpdate);
+}, []);
+
+// GOOD — cleanup on unmount
+useEffect(() => {
+  socket.on('orderUpdate', handleUpdate);
+  return () => socket.off('orderUpdate', handleUpdate);
+}, []);
+```
+
+**2. Timers not cleared**
+```typescript
+// BAD — interval runs forever
+useEffect(() => {
+  setInterval(pollStatus, 5000);
+}, []);
+
+// GOOD — clear on unmount
+useEffect(() => {
+  const id = setInterval(pollStatus, 5000);
+  return () => clearInterval(id);
+}, []);
+```
+
+**3. Closures holding stale references**
+```typescript
+// BAD — closure captures entire component scope
+const heavyCallback = () => {
+  processLargeDataset(allOrders);  // Holds reference to allOrders
+};
+
+// GOOD — use ref for latest value without capturing
+const ordersRef = useRef(allOrders);
+ordersRef.current = allOrders;
+const heavyCallback = useCallback(() => {
+  processLargeDataset(ordersRef.current);
+}, []);
+```
+
+### Large List Memory Patterns
+
+For lists with 1000+ items:
+
+| Strategy | When | Implementation |
+|----------|------|---------------|
+| Windowed rendering | Always for large lists | FlatList (RN) / ListView.builder (Flutter) |
+| Pagination | Server-side data | Load 20 items, fetch more on scroll |
+| Cursor-based infinite scroll | Feed-style data | `onEndReached` + cursor token |
+| Section list | Grouped data | SectionList (RN) / SliverList with headers |
+
+```typescript
+// Infinite scroll with cursor pagination
+function useInfiniteOrders() {
+  return useInfiniteQuery({
+    queryKey: ['orders'],
+    queryFn: ({ pageParam }) => orderApi.list({ cursor: pageParam, limit: 20 }),
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    initialPageParam: undefined,
+  });
+}
+
+// In component
+<FlatList
+  data={orders.pages.flatMap((p) => p.items)}
+  onEndReached={() => {
+    if (hasNextPage && !isFetchingNextPage) fetchNextPage();
+  }}
+  onEndReachedThreshold={0.5}
+  ListFooterComponent={isFetchingNextPage ? <Spinner /> : null}
+/>
+```
+
+## Network Optimization
+
+### Request Batching
+Combine multiple small requests into one when possible.
+
+```typescript
+// BAD — 5 separate requests on screen load
+const user = await api.getUser(id);
+const orders = await api.getOrders(id);
+const addresses = await api.getAddresses(id);
+const favorites = await api.getFavorites(id);
+const notifications = await api.getNotifications(id);
+
+// GOOD — single batched request
+const { user, orders, addresses, favorites, notifications } =
+  await api.getUserDashboard(id);
+```
+
+### Caching Strategies
+
+| Strategy | TTL | Use Case |
+|----------|-----|----------|
+| Cache first, revalidate in background | 30s–5min | Order list, product catalog |
+| Network first, cache fallback | 0 | Payment status, real-time data |
+| Cache only | 24h+ | App config, static content |
+| Stale-while-revalidate | 5min | User profile, settings |
+
+```typescript
+// TanStack Query — stale-while-revalidate
+useQuery({
+  queryKey: ['products', categoryId],
+  queryFn: () => productApi.list(categoryId),
+  staleTime: 5 * 60 * 1000,  // Fresh for 5 minutes
+  gcTime: 30 * 60 * 1000,    // Keep in cache 30 minutes
+});
+```
+
+### Offline Fallback
+
+```typescript
+// Network-aware fetcher with offline fallback
+async function fetchWithOfflineFallback<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+): Promise<T> {
+  try {
+    const data = await fetcher();
+    await localCache.set(key, data);  // Update cache
+    return data;
+  } catch (error) {
+    if (isNetworkError(error)) {
+      const cached = await localCache.get<T>(key);
+      if (cached) return cached;
+    }
+    throw error;
+  }
+}
+```
+
+## Startup Optimization
+
+### Splash Screen Strategy
+
+```
+Cold start timeline:
+├── 0ms    OS launches process
+├── 100ms  Native splash screen shows (configured in native project)
+├── 300ms  JS/Dart engine initializes
+├── 500ms  App component mounts
+├── 800ms  Critical data fetched (auth check, config)
+├── 1000ms Home screen renders
+└── 1200ms Splash hides, app interactive
+Target: < 1.5s cold start
+```
+
+### Lazy Initialization
+Don't initialize everything at app launch.
+
+```typescript
+// BAD — everything initialized at startup
+function App() {
+  initAnalytics();
+  initCrashReporting();
+  initFeatureFlags();
+  initDeepLinking();
+  initPushNotifications();
+  prefetchAllData();
+  return <Navigator />;
+}
+
+// GOOD — only init critical services at startup
+function App() {
+  useEffect(() => {
+    // Critical — init immediately
+    initCrashReporting();
+    initAuth();
+
+    // Deferred — init after first render
+    InteractionManager.runAfterInteractions(() => {
+      initAnalytics();
+      initFeatureFlags();
+      initDeepLinking();
+    });
+
+    // Lazy — init when needed
+    // Push notifications: init after user completes onboarding
+    // Prefetch: only prefetch current screen's data
+  }, []);
+
+  return <Navigator />;
+}
+```
+
+### Code Splitting (React Native)
+Use `React.lazy` for screens not immediately visible:
+
+```typescript
+// Lazy-load screens that are not on the initial stack
+const SettingsScreen = React.lazy(() => import('./screens/SettingsScreen'));
+const ProfileScreen = React.lazy(() => import('./screens/ProfileScreen'));
+
+// Hermes bytecode precompilation — ensure metro config is set
+// metro.config.js
+module.exports = { transformer: { hermesParser: true } };
+```
+
+## Battery Optimization
+
+### Background Task Guidelines
+
+| Task | Approach | Frequency |
+|------|----------|-----------|
+| Data sync | WorkManager (Android) / BGTaskScheduler (iOS) | Every 15-30 min |
+| Location tracking | Significant location changes, not continuous GPS | On significant movement |
+| Push handling | Silent push triggers minimal work | Event-driven |
+| File upload | Background transfer API | On WiFi only |
+
+### Location Tracking Efficiency
+
+```typescript
+// BAD — continuous high-accuracy tracking
+watchPosition({ enableHighAccuracy: true, distanceFilter: 0 });
+
+// GOOD — balanced accuracy based on use case
+const locationConfig = {
+  delivery_tracking: {
+    enableHighAccuracy: true,
+    distanceFilter: 50,       // Update every 50 meters
+    interval: 10_000,         // Android: every 10 seconds
+  },
+  store_finder: {
+    enableHighAccuracy: false,  // Cell/WiFi is good enough
+    distanceFilter: 500,
+    maximumAge: 60_000,         // Accept 1-minute-old location
+  },
+  background_geofence: {
+    // Use geofencing API instead of polling
+    // Triggers only when entering/exiting defined regions
+  },
+};
+```
+
+## App Size Optimization
+
+### Size Budget
+
+| Category | Target | Approach |
+|----------|--------|----------|
+| Android APK | < 30 MB | AAB + dynamic delivery |
+| iOS IPA | < 50 MB | Asset catalogs + on-demand resources |
+| JS bundle (RN) | < 5 MB | Tree shaking + lazy imports |
+| Images | < 10 MB total | WebP + appropriate resolution |
+| Fonts | < 2 MB | Subset fonts to used characters |
+
+### Asset Optimization
+
+```bash
+# Android — use App Bundle for size optimization
+# Automatically splits by density, ABI, and language
+./gradlew bundleRelease
+
+# iOS — enable bitcode and asset optimization
+# In Xcode: Build Settings → Enable Bitcode = YES
+# Use asset catalogs for automatic thinning
+
+# React Native — analyze bundle size
+npx react-native-bundle-visualizer
+
+# Flutter — analyze app size
+flutter build apk --analyze-size
+flutter build ios --analyze-size
+```
+
+### Tree Shaking and Dead Code
+
+```typescript
+// BAD — imports entire library
+import _ from 'lodash';
+const sorted = _.sortBy(items, 'date');
+
+// GOOD — import only what you need
+import sortBy from 'lodash/sortBy';
+const sorted = sortBy(items, 'date');
+
+// BETTER — use native methods when possible
+const sorted = [...items].sort((a, b) => a.date.localeCompare(b.date));
+```
+
+## Testing Strategy
+
+### Testing Pyramid for Mobile
+
+```
+         ╱╲
+        ╱  ╲         E2E Tests (Detox / integration_test)
+       ╱ 10% ╲       Full user flows on real device/simulator
+      ╱────────╲
+     ╱          ╲     Component/Widget Tests
+    ╱    30%     ╲    Render + interact + assert
+   ╱──────────────╲
+  ╱                ╲   Unit Tests
+ ╱      60%        ╲   Business logic, utilities, stores
+╱────────────────────╲
+```
+
+### Unit Tests
+
+```typescript
+// Test business logic in isolation
+describe('CartStore', () => {
+  it('calculates total correctly', () => {
+    const store = useCartStore.getState();
+    store.addItem({ id: '1', name: 'Pizza', price: 12.99, quantity: 2 });
+    store.addItem({ id: '2', name: 'Drink', price: 3.50, quantity: 1 });
+    expect(store.total()).toBe(29.48);
+  });
+
+  it('removes item by id', () => {
+    const store = useCartStore.getState();
+    store.addItem({ id: '1', name: 'Pizza', price: 12.99, quantity: 1 });
+    store.removeItem('1');
+    expect(store.items).toHaveLength(0);
+  });
+});
+```
+
+### Component / Widget Tests
+
+```typescript
+// React Native — Testing Library
+it('shows order details and navigates on press', () => {
+  const onPress = jest.fn();
+  render(<OrderCard order={mockOrder} onPress={onPress} />);
+
+  expect(screen.getByText('Pizza Margherita')).toBeTruthy();
+  expect(screen.getByText('$12.99')).toBeTruthy();
+
+  fireEvent.press(screen.getByText('Pizza Margherita'));
+  expect(onPress).toHaveBeenCalledTimes(1);
+});
+```
+
+```dart
+// Flutter — widget test
+testWidgets('OrderCard shows details and responds to tap', (tester) async {
+  var tapped = false;
+  await tester.pumpWidget(MaterialApp(
+    home: OrderCard(order: mockOrder, onTap: () => tapped = true),
+  ));
+
+  expect(find.text('Pizza Margherita'), findsOneWidget);
+  expect(find.text('\$12.99'), findsOneWidget);
+
+  await tester.tap(find.text('Pizza Margherita'));
+  expect(tapped, isTrue);
+});
+```
+
+### E2E Tests
+
+```typescript
+// Detox (React Native) — full user flow
+describe('Order Flow', () => {
+  beforeAll(async () => {
+    await device.launchApp({ newInstance: true });
+  });
+
+  it('places an order successfully', async () => {
+    await element(by.id('menu-tab')).tap();
+    await element(by.text('Pizza Margherita')).tap();
+    await element(by.id('add-to-cart')).tap();
+    await element(by.id('cart-tab')).tap();
+    await expect(element(by.text('1 item'))).toBeVisible();
+    await element(by.id('checkout-button')).tap();
+    await element(by.id('confirm-order')).tap();
+    await expect(element(by.text('Order Confirmed'))).toBeVisible();
+  });
+});
+```
+
+## Platform-Specific Optimizations
+
+### iOS
+
+| Optimization | Implementation |
+|-------------|---------------|
+| Large Title navigation | Use `headerLargeTitle: true` for content screens |
+| Haptic feedback | `UIImpactFeedbackGenerator` on key interactions |
+| Dynamic Type | Support system font scaling in all text |
+| Safe Area | Always use `SafeAreaView` / `SafeArea` |
+| ProMotion (120Hz) | Ensure animations use native driver |
+
+### Android
+
+| Optimization | Implementation |
+|-------------|---------------|
+| Material 3 / Dynamic Color | Use `DynamicColorTheme` on Android 12+ |
+| Predictive back gesture | Handle back navigation with animation preview |
+| Edge-to-edge display | Draw behind system bars with proper insets |
+| App Startup library | Lazy-init content providers |
+| Baseline Profiles | Generate profiles for critical user paths |
+
+### Shared Checklist
+
+Before every release:
+- [ ] Test on oldest supported OS version
+- [ ] Test on lowest-tier target device
+- [ ] Profile startup time (cold + warm)
+- [ ] Check memory usage over 10-minute session
+- [ ] Verify offline behavior
+- [ ] Run accessibility scanner
+- [ ] Check battery usage in background
+- [ ] Verify deep links work from terminated state

package/data/shared/framework/skills/mobile-development/references/troubleshooting.md

@@ -0,0 +1,158 @@
+# Mobile Development Troubleshooting Guide
+
+## iOS Build Failures
+
+### CocoaPods version conflicts
+**Symptom:** `Pod install` fails with version incompatibility or spec repo errors.
+```bash
+# Reset CocoaPods cache and reinstall
+cd ios && pod deintegrate && pod cache clean --all
+rm -rf Pods Podfile.lock
+pod repo update
+pod install --verbose
+```
+
+### Xcode compatibility issues
+**Symptom:** Build fails after Xcode update with framework or SDK errors.
+- Check minimum deployment target matches all pod requirements.
+- Update `IPHONEOS_DEPLOYMENT_TARGET` in Podfile: `platform :ios, '15.0'`.
+- Clean derived data: `rm -rf ~/Library/Developer/Xcode/DerivedData`.
+- Reset package caches: Xcode → File → Packages → Reset Package Caches.
+
+### Code signing failures
+**Symptom:** `Signing requires a development team`, provisioning profile errors.
+1. Verify team ID in Xcode → Signing & Capabilities.
+2. Check provisioning profile: `security find-identity -p codesigning -v`.
+3. For CI: ensure certificates are in the keychain and profiles in `~/Library/MobileDevice/Provisioning Profiles/`.
+4. Revoke and regenerate if expired: Apple Developer Portal → Certificates.
+
+## Android Build Failures
+
+### Gradle version issues
+**Symptom:** `Could not determine the dependencies of task`, Gradle sync fails.
+```bash
+# Clean and rebuild
+cd android && ./gradlew clean
+rm -rf .gradle build app/build
+./gradlew assembleDebug --stacktrace
+```
+- Check `gradle-wrapper.properties` distribution URL matches project requirements.
+- Verify `com.android.tools.build:gradle` version in root `build.gradle` is compatible.
+
+### NDK configuration errors
+**Symptom:** `NDK not configured` or native build failures.
+- Set `ndk.dir` in `local.properties` or `ANDROID_NDK_HOME` env variable.
+- Ensure NDK version matches: check `ndkVersion` in `app/build.gradle`.
+- Install via SDK Manager: `sdkmanager "ndk;25.2.9519653"`.
+
+### Keystore issues
+**Symptom:** `keystore was tampered with, or password was incorrect`.
+- Verify keystore path and password in `gradle.properties` or environment variables.
+- List keystore contents: `keytool -list -v -keystore release.keystore`.
+- Never commit keystores to git — use CI secrets management.
+
+## React Native Red Screen Common Causes
+
+**Top causes and fixes:**
+1. **Native module not linked** — `null is not an object (evaluating 'NativeModule.method')`.
+   - Fix: `cd ios && pod install` or rebuild the app. Auto-linking should handle most cases in RN 0.60+.
+2. **Metro bundler cache stale** — Mysterious errors after dependency changes.
+   - Fix: `npx react-native start --reset-cache`.
+3. **Version mismatch** — JS bundle and native code out of sync.
+   - Fix: Clean build → `cd android && ./gradlew clean && cd ../ios && pod install` → rebuild.
+4. **Missing return statement** — Component returns `undefined`.
+   - Fix: Ensure all code paths return valid JSX or `null`.
+
+## App Crash on Startup
+
+**Diagnosis workflow:**
+1. **iOS:** Check Xcode console or `Console.app` for crash logs.
+2. **Android:** `adb logcat *:E | grep -i "fatal\|crash\|exception"`.
+3. **React Native:** Look for "RCTFatalException" or "java.lang.RuntimeException".
+
+**Common causes:**
+1. **Native module initialization failure** — A module's `init` method crashes.
+   - Fix: Check native module compatibility with your RN version. Update or patch.
+2. **Missing required permissions** — App accesses hardware before permission granted.
+   - Fix: Add permission checks before accessing camera, location, etc.
+3. **Invalid app configuration** — Malformed `Info.plist` or `AndroidManifest.xml`.
+   - Fix: Validate XML, check for required keys (e.g., `NSCameraUsageDescription`).
+4. **ProGuard stripping required classes** — Release build crashes, debug works fine.
+   - Fix: Add keep rules in `proguard-rules.pro` for libraries that use reflection.
+
+## JS Thread vs UI Thread Performance Profiling
+
+**Diagnosis:**
+1. Enable React Native Performance Monitor: shake device → "Perf Monitor".
+2. Two frame rates shown: UI thread (native animations) and JS thread (logic/rendering).
+3. If **JS thread drops** but UI is smooth: heavy JavaScript computation.
+4. If **UI thread drops**: native view hierarchy too complex or heavy native animations.
+
+**JS thread optimization:**
+- Move heavy computation to `InteractionManager.runAfterInteractions()`.
+- Use `useMemo` / `useCallback` to prevent unnecessary recalculations.
+- Offload work to native modules or JSI for CPU-intensive tasks.
+
+**UI thread optimization:**
+- Use `Animated` with `useNativeDriver: true` for animations.
+- Flatten view hierarchy — deep nesting degrades native layout performance.
+- Use `removeClippedSubviews` on long `FlatList` components.
+
+## Push Notification Not Received
+
+### iOS checklist
+- [ ] APNs certificate/key is valid and not expired (check in Apple Developer Portal).
+- [ ] Correct environment: sandbox for dev, production for release.
+- [ ] Device token is registered and sent to backend.
+- [ ] `UIBackgroundModes` includes `remote-notification` in `Info.plist`.
+- [ ] User granted notification permission (check `UNUserNotificationCenter` authorization status).
+- [ ] Silent notifications: `content-available: 1` header set, app has background mode enabled.
+
+### Android checklist
+- [ ] `google-services.json` is up to date and in `app/` directory.
+- [ ] FCM server key matches the project in Firebase Console.
+- [ ] Device has Google Play Services (or use fallback for Huawei).
+- [ ] Notification channel created (required for Android 8+).
+- [ ] Battery optimization not killing the app: Settings → Apps → Battery → Unrestricted.
+- [ ] Test with `adb shell am broadcast` or Firebase Console test message.
+
+## Deep Links Not Working
+
+**Verification steps:**
+1. **iOS Universal Links:**
+   - Verify `apple-app-site-association` file: `curl -v https://yourdomain.com/.well-known/apple-app-site-association`.
+   - Must return `application/json` content type (not served as download).
+   - Check `applinks:` entitlement in Xcode → Signing & Capabilities.
+   - Test: `xcrun simctl openurl booted "https://yourdomain.com/path"`.
+
+2. **Android App Links:**
+   - Verify `assetlinks.json`: `curl https://yourdomain.com/.well-known/assetlinks.json`.
+   - Check `intent-filter` in `AndroidManifest.xml` has `autoVerify="true"`.
+   - Verify: `adb shell pm get-app-links <package_name>`.
+   - Test: `adb shell am start -a android.intent.action.VIEW -d "https://yourdomain.com/path"`.
+
+3. **Custom URI schemes** (`myapp://path`):
+   - Simpler but less secure — any app can register the same scheme.
+   - Test: `adb shell am start -a android.intent.action.VIEW -d "myapp://path"`.
+
+## App Store / Play Store Rejection Common Reasons
+
+### Apple App Store
+1. **Crash on review** — Test on the exact iOS version and device type reviewers use (latest).
+   - Fix: Test on physical device with release build before submitting.
+2. **Missing privacy policy** — Required for all apps.
+3. **Incomplete metadata** — Screenshots missing for required device sizes.
+4. **Non-HTTPS network calls** — ATS (App Transport Security) violations.
+   - Fix: Ensure all API calls use HTTPS. Remove ATS exceptions.
+5. **Guideline 4.3 (Spam)** — App too similar to existing apps or is a web wrapper.
+   - Fix: Add meaningful native functionality beyond the website.
+
+### Google Play Store
+1. **Target API level too low** — Must target recent Android API level.
+   - Fix: Update `targetSdkVersion` in `build.gradle` to the required level.
+2. **Missing Data Safety section** — Required disclosure of data collection practices.
+3. **Deceptive permissions** — Requesting permissions not justified by app functionality.
+   - Fix: Remove unnecessary permissions, add clear rationale for required ones.
+4. **Policy violation on user data** — Collecting data without consent disclosure.
+   - Fix: Add consent dialogs, update privacy policy.
+5. **Crashes on specific devices** — Test with Firebase Test Lab across device matrix.