@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

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

@@ -1,465 +0,0 @@
-# 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**: Broad adoption and familiarity among mobile developers
-- **Performance**: Near-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**: Broad adoption among mobile developers
-- **Performance**: Near-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**: Native performance
-- **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**: Native performance
-- **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**: 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
-- Type-safe navigation with TypeScript
-- Deep linking configuration
-- Tab, stack, drawer navigators
-
-**TypeScript Adoption**
-- TypeScript is common in new React Native projects
-- Type safety helps prevent 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
-
-**❌ 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 test-runner) async {
-  await test-runner.pumpWidget(MyApp());
-
-  expect(find.text('0'), findsOneWidget);
-  expect(find.text('1'), findsNothing);
-
-  await test-runner.tap(find.byIcon(Icons.add));
-  await test-runner.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, 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)
-- Widely adopted 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