ai-qakit 1.0.0

package/templates/.claude/skills/mobile-development/references/mobile-frameworks.md

@@ -0,0 +1,465 @@
+# Mobile Frameworks Reference
+
+Comprehensive guide to mobile development frameworks: React Native, Flutter, and native development.
+
+## Framework Overview (2024-2025)
+
+### React Native
+- **Language**: JavaScript/TypeScript
+- **Stars**: 121,000+ on GitHub
+- **Adoption**: 35% of mobile developers, 67% familiarity
+- **Performance**: 80-90% native performance
+- **Architecture**: Bridge-based (legacy) → New Architecture (JSI, Fabric, Codegen)
+- **Rendering**: Native components
+- **Hot Reload**: Yes
+- **Community**: Huge (npm ecosystem, 3M+ downloads/week)
+
+### Flutter
+- **Language**: Dart
+- **Stars**: 170,000+ on GitHub (fastest-growing)
+- **Adoption**: 46% of mobile developers
+- **Performance**: 85-95% native performance
+- **Architecture**: "Everything is a widget"
+- **Rendering**: Custom Impeller rendering engine (eliminates jank)
+- **Hot Reload**: Yes (fastest in industry)
+- **Community**: Growing rapidly (23,000+ packages on pub.dev)
+
+### Native iOS (Swift/SwiftUI)
+- **Language**: Swift
+- **Performance**: 100% native
+- **UI Framework**: SwiftUI (declarative) or UIKit (imperative)
+- **Latest**: Swift 6 with compile-time data race detection
+- **Tooling**: Xcode 16, Swift Package Manager
+- **Concurrency**: async/await, actors, @MainActor
+
+### Native Android (Kotlin/Jetpack Compose)
+- **Language**: Kotlin
+- **Performance**: 100% native
+- **UI Framework**: Jetpack Compose (declarative) or Views (imperative)
+- **Latest**: Kotlin 2.1, Compose 1.7
+- **Tooling**: Android Studio Hedgehog+
+- **Coroutines**: Kotlin coroutines for async
+
+## React Native Deep Dive
+
+### Core Concepts
+
+**New Architecture (0.82+ Mandatory)**
+- **JSI (JavaScript Interface)**: Direct JS-to-native communication, eliminating bridge
+- **Fabric**: New rendering system with synchronous layout
+- **Codegen**: Static type safety between JS and native code
+- **Turbo Modules**: Lazy-loaded native modules
+
+**Performance Optimizations**
+- **Hermes Engine**: 30-40% faster startup, reduced memory
+- **Native Driver Animations**: Offloaded to UI thread (60 FPS)
+- **FlatList Virtualization**: Renders only visible items
+- **Image Optimization**: FastImage library, progressive loading
+
+### Best Practices
+
+**Project Structure (Feature-Based)**
+```
+src/
+├── features/
+│   ├── auth/
+│   ├── profile/
+│   └── dashboard/
+├── shared/
+│   ├── components/
+│   ├── hooks/
+│   └── utils/
+├── navigation/
+├── services/
+└── stores/
+```
+
+**State Management (2024-2025)**
+1. **Zustand** (Rising Star): Minimal boilerplate, 3KB, excellent TypeScript
+2. **Redux Toolkit**: Enterprise apps, time-travel debugging, DevTools
+3. **Recoil**: Meta-built, atom-based, experimental
+4. **Context API**: Simple apps, avoid prop drilling
+
+**Navigation**
+- **React Navigation**: Industry standard, 80%+ adoption
+- Type-safe navigation with TypeScript
+- Deep linking configuration
+- Tab, stack, drawer navigators
+
+**TypeScript Adoption**
+- 85%+ of new React Native projects use TypeScript
+- Type safety prevents 15% of runtime errors
+- Better IDE support and autocomplete
+
+### Testing Strategy
+
+**Unit Testing**
+- **Jest**: Default test runner
+- **React Native Testing Library**: Component testing, best practices
+- Target: 70-80%+ code coverage
+
+**E2E Testing**
+- **Detox**: Gray-box testing, fast, reliable (recommended)
+- **Appium**: Cross-platform, WebDriver-based
+- **Maestro**: New player, simple YAML-based tests
+
+**Example (React Native Testing Library)**
+```javascript
+import { render, fireEvent, waitFor } from '@testing-library/react-native';
+
+test('login button should be enabled when form is valid', async () => {
+  const { getByTestId } = render(<LoginScreen />);
+  const emailInput = getByTestId('email-input');
+  const passwordInput = getByTestId('password-input');
+  const loginButton = getByTestId('login-button');
+
+  fireEvent.changeText(emailInput, 'test@example.com');
+  fireEvent.changeText(passwordInput, 'password123');
+
+  await waitFor(() => {
+    expect(loginButton).not.toBeDisabled();
+  });
+});
+```
+
+### When to Choose React Native
+
+**✅ Best For:**
+- JavaScript/TypeScript expertise in team
+- Code sharing with web (React)
+- Rapid prototyping and MVPs
+- Strong community support needed
+- npm ecosystem integration
+- Commercial apps (12.57% market share)
+
+**❌ Not Ideal For:**
+- Heavy graphics/gaming (use native or Unity)
+- Maximum performance critical
+- Deep platform-specific integrations
+- Team unfamiliar with JavaScript
+
+## Flutter Deep Dive
+
+### Core Concepts
+
+**"Everything is a Widget"**
+- UI built from composable widgets
+- Immutable widget tree
+- Reactive updates with setState/state management
+
+**Rendering Engine**
+- **Impeller**: New rendering engine (iOS stable, Android preview)
+- Eliminates shader jank
+- 120 FPS capable on capable devices
+- Custom Skia-based rendering (full control)
+
+**Performance Features**
+- **Const widgets**: Compile-time optimization
+- **RepaintBoundary**: Isolate expensive repaints
+- **ListView.builder**: Lazy loading for long lists
+- **Cached network images**: Image optimization
+
+### Best Practices
+
+**Project Structure (Feature-First)**
+```
+lib/
+├── features/
+│   ├── auth/
+│   │   ├── data/
+│   │   ├── domain/
+│   │   └── presentation/
+│   └── profile/
+├── core/
+│   ├── theme/
+│   ├── utils/
+│   └── widgets/
+├── routing/
+└── main.dart
+```
+
+**State Management (2024-2025)**
+1. **Riverpod 3**: Modern, compile-safe, recommended by Flutter team
+2. **Bloc**: Enterprise apps, event-driven, predictable state
+3. **Provider**: Beginners, simple apps
+4. **GetX**: All-in-one (state + routing + DI), opinionated
+
+**Navigation**
+- **GoRouter**: Official recommendation (2024+), declarative routing
+- Type-safe routes with code generation
+- Deep linking built-in
+- Replaces Navigator 2.0 for most use cases
+
+**Priority Levels (Official)**
+1. **P0**: Fix immediately (crashes, data loss)
+2. **P1**: Fix within days (major features broken)
+3. **P2**: Fix within weeks (annoyances)
+4. **P3**: Nice to have
+
+### Testing Strategy
+
+**Unit Testing**
+- **flutter_test**: Built-in testing package
+- **Mockito**: Mocking dependencies
+- Target: 80%+ code coverage
+
+**Widget Testing**
+- **WidgetTester**: Test UI and interactions
+- **Golden Tests**: Visual regression testing
+
+**Integration Testing**
+- **integration_test**: End-to-end testing
+- Run on real devices or emulators
+
+**Example (Widget Testing)**
+```dart
+testWidgets('Counter increments', (WidgetTester tester) async {
+  await tester.pumpWidget(MyApp());
+
+  expect(find.text('0'), findsOneWidget);
+  expect(find.text('1'), findsNothing);
+
+  await tester.tap(find.byIcon(Icons.add));
+  await tester.pump();
+
+  expect(find.text('0'), findsNothing);
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+### When to Choose Flutter
+
+**✅ Best For:**
+- Performance-critical applications
+- Complex animations and custom UI
+- Multi-platform (mobile, web, desktop)
+- Consistent UI across platforms
+- Growing team/startup (fastest development)
+- Apps with heavy visual requirements
+
+**❌ Not Ideal For:**
+- Team unfamiliar with Dart
+- Heavy reliance on native platform features
+- Existing large JavaScript/native codebase
+- Small app size critical (<20MB)
+
+## Native iOS (Swift/SwiftUI)
+
+### Core Concepts
+
+**Swift 6 (2024-2025)**
+- Compile-time data race detection
+- Enhanced concurrency: async/await, actors, @MainActor
+- Powerful macro system
+- Move semantics for performance
+
+**SwiftUI vs UIKit**
+- **SwiftUI**: Declarative, 40% less code, iOS 13+, modern approach
+- **UIKit**: Imperative, fine-grained control, legacy support, complex customizations
+- Both work together in same project
+
+### Architecture Patterns
+
+**MVVM (Most Popular)**
+```swift
+// ViewModel (ObservableObject)
+class LoginViewModel: ObservableObject {
+    @Published var email = ""
+    @Published var password = ""
+    @Published var isLoading = false
+
+    func login() async {
+        isLoading = true
+        // Login logic
+        isLoading = false
+    }
+}
+
+// View
+struct LoginView: View {
+    @StateObject private var viewModel = LoginViewModel()
+
+    var body: some View {
+        VStack {
+            TextField("Email", text: $viewModel.email)
+            SecureField("Password", text: $viewModel.password)
+            Button("Login") {
+                Task { await viewModel.login() }
+            }
+        }
+    }
+}
+```
+
+**TCA (The Composable Architecture)**
+- Growing adoption (v1.13+)
+- Excellent for complex apps
+- Steeper learning curve
+- Predictable state management
+
+### When to Choose Native iOS
+
+**✅ Best For:**
+- iOS-only applications
+- Maximum performance required
+- Latest Apple features (WidgetKit, Live Activities, App Clips)
+- Deep iOS ecosystem integration
+- Team with Swift/iOS expertise
+
+## Native Android (Kotlin/Jetpack Compose)
+
+### Core Concepts
+
+**Kotlin 2.1 (2024-2025)**
+- Null safety by design
+- Coroutines for async
+- Sealed classes for type-safe states
+- Extension functions
+
+**Jetpack Compose**
+- Declarative UI (like SwiftUI/React)
+- 60% adoption in top 1,000 apps
+- Material Design 3 integration
+- Compose compiler with Kotlin 2.0+
+
+### Architecture Patterns
+
+**MVVM + Clean Architecture**
+```kotlin
+// ViewModel
+class LoginViewModel(
+    private val loginUseCase: LoginUseCase
+) : ViewModel() {
+    private val _uiState = MutableStateFlow(LoginUiState())
+    val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()
+
+    fun login(email: String, password: String) {
+        viewModelScope.launch {
+            _uiState.update { it.copy(isLoading = true) }
+            loginUseCase(email, password)
+                .onSuccess { /* Navigate */ }
+                .onFailure { /* Show error */ }
+            _uiState.update { it.copy(isLoading = false) }
+        }
+    }
+}
+
+// Composable
+@Composable
+fun LoginScreen(viewModel: LoginViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsState()
+
+    Column {
+        TextField(
+            value = uiState.email,
+            onValueChange = { /* update */ }
+        )
+        Button(onClick = { viewModel.login() }) {
+            Text("Login")
+        }
+    }
+}
+```
+
+### When to Choose Native Android
+
+**✅ Best For:**
+- Android-only applications
+- Maximum performance required
+- Material Design 3 implementation
+- Deep Android ecosystem integration
+- Team with Kotlin/Android expertise
+
+## Framework Comparison Matrix
+
+| Feature | React Native | Flutter | Native iOS | Native Android |
+|---------|--------------|---------|------------|----------------|
+| **Language** | JavaScript/TS | Dart | Swift | Kotlin |
+| **Learning Curve** | Easy | Medium | Medium | Medium |
+| **Performance** | 80-90% | 85-95% | 100% | 100% |
+| **Hot Reload** | Yes | Yes (fastest) | Previews | Live Edit |
+| **Code Sharing** | Web (React) | Web/Desktop | No | No |
+| **Community Size** | Huge | Growing | iOS only | Android only |
+| **UI Paradigm** | Components | Widgets | Declarative | Declarative |
+| **Third-party** | npm (3M+) | pub.dev (23K+) | SPM | Maven |
+| **App Size** | 40-50MB | 15-20MB | 10-15MB | 10-15MB |
+| **Build Time** | Medium | Fast | Slow (Xcode) | Medium |
+| **Debugging** | Chrome/Safari | DevTools | Xcode | Android Studio |
+| **Platform Feel** | Needs work | Needs work | Native | Native |
+| **Startup Time** | Medium | Fast | Fastest | Fastest |
+| **Best For** | JS teams | Performance | iOS-only | Android-only |
+
+## Migration Paths
+
+### React Native → Flutter
+- **Effort**: High (complete rewrite)
+- **Timeline**: 3-6 months for medium app
+- **Benefits**: Better performance, smaller app size
+- **Challenges**: New language (Dart), different ecosystem
+
+### Flutter → React Native
+- **Effort**: High (complete rewrite)
+- **Timeline**: 3-6 months for medium app
+- **Benefits**: Larger community, web code sharing
+- **Challenges**: Lower performance, larger app size
+
+### Cross-Platform → Native
+- **Effort**: Very High (separate iOS and Android apps)
+- **Timeline**: 6-12 months for medium app
+- **Benefits**: Maximum performance, platform features
+- **Challenges**: Maintain two codebases, 2x team size
+
+### Native → Cross-Platform
+- **Effort**: High (consolidate to one codebase)
+- **Timeline**: 4-8 months for medium app
+- **Benefits**: Single codebase, faster development
+- **Challenges**: Performance tradeoffs, platform differences
+
+## Decision Framework
+
+### Start Here: Do you need native performance?
+- **No** → Cross-platform (React Native or Flutter)
+- **Yes** → Native (Swift or Kotlin)
+
+### If Cross-Platform: Does team know JavaScript?
+- **Yes** → React Native
+- **No** → Flutter
+
+### If Native: iOS-only or Android-only?
+- **iOS-only** → Swift/SwiftUI
+- **Android-only** → Kotlin/Compose
+- **Both** → Reconsider cross-platform
+
+### Additional Factors:
+- **Existing codebase**: Use same technology
+- **Web app exists**: React Native (code sharing)
+- **Desktop needed**: Flutter (multi-platform)
+- **Budget constrained**: Cross-platform
+- **Performance critical**: Native
+- **Complex animations**: Flutter or Native
+- **Commercial focus**: React Native (larger market share)
+
+## Resources
+
+**React Native:**
+- Official Docs: https://reactnative.dev/
+- New Architecture: https://reactnative.dev/docs/the-new-architecture/landing-page
+- Expo: https://expo.dev/ (recommended framework)
+- Directory: https://reactnative.directory/
+
+**Flutter:**
+- Official Docs: https://flutter.dev/
+- Pub.dev: https://pub.dev/
+- Codelabs: https://flutter.dev/codelabs
+- Widget Catalog: https://flutter.dev/widgets
+
+**Native iOS:**
+- Swift Docs: https://swift.org/documentation/
+- SwiftUI Tutorials: https://developer.apple.com/tutorials/swiftui
+- iOS HIG: https://developer.apple.com/design/human-interface-guidelines/
+
+**Native Android:**
+- Kotlin Docs: https://kotlinlang.org/docs/home.html
+- Compose Docs: https://developer.android.com/jetpack/compose
+- Material 3: https://m3.material.io/
+- Android Guides: https://developer.android.com/guide