create-disposabl-app 0.1.0 → 0.1.1

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-platform-setup.md

@@ -0,0 +1,112 @@
+---
+title: Platform Differences
+impact: MEDIUM
+tags: ios, android, xcode, gradle, cocoapods
+---
+
+# Skill: Platform Differences
+
+Navigate iOS and Android tooling, dependency management, and build systems in React Native.
+
+## Quick Reference
+
+| Platform | IDE | Package Manager | Build System |
+|----------|-----|-----------------|--------------|
+| JavaScript | VS Code | npm/yarn/pnpm/bun | Metro |
+| iOS | Xcode | CocoaPods | xcodebuild |
+| Android | Android Studio | Gradle | Gradle |
+
+```bash
+# Common commands
+bundle install                      # Install ruby bundler
+cd ios && bundle exec pod install   # Install CocoaPods deps
+cd android && ./gradlew tasks       # Verify Gradle wrapper and tasks
+xed ios/                            # Open Xcode
+```
+
+## When to Use
+
+- Setting up native development environment
+- Adding native dependencies
+- Debugging platform-specific issues
+- Understanding build processes
+
+## Dependency Management
+
+React Native autolinking only handles libraries structured as React Native modules. React Native packages often ship native iOS/Android code through npm, then CocoaPods/Gradle reference local files from `node_modules`. Pure native dependencies still need Podfile or Gradle changes.
+
+### JavaScript (npm/yarn/pnpm/bun)
+
+Infer package manager from lockfile: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`.
+
+### iOS (CocoaPods)
+
+```bash
+# Install pods after npm install
+bundle install
+cd ios && bundle exec pod install
+
+# Key files
+ios/Podfile           # Pod dependencies
+ios/Pods/             # Installed pods (gitignored)
+ios/*.xcworkspace     # Open this in Xcode (not .xcodeproj)
+Gemfile               # Ruby/CocoaPods version
+```
+
+
+### Android (Gradle)
+
+```bash
+# Verify Gradle after adding dependencies
+cd android && ./gradlew tasks
+
+# Key files
+android/build.gradle           # Project-level config
+android/app/build.gradle       # App dependencies
+android/gradle.properties      # Build flags
+android/gradlew                # Gradle wrapper
+```
+
+Use exact Gradle dependency versions in production. Avoid dynamic `+` versions because they can change builds unpredictably.
+
+## Common Commands
+
+```bash
+# iOS
+bundle install                         # Install ruby bundler
+cd ios && bundle exec pod install      # Install pods
+xcrun simctl list                      # List simulators
+
+# Android  
+cd android && ./gradlew clean          # Clean build
+./gradlew tasks                        # List available tasks
+./gradlew assembleRelease              # Build release APK
+
+# React Native CLI
+npx react-native start                 # Start Metro
+npx react-native run-ios               # Run on iOS
+npx react-native run-android           # Run on Android
+
+# Expo
+npx expo start                         # Start Metro (Expo)
+npx expo run:ios                       # Run on iOS (dev client)
+npx expo run:android                   # Run on Android (dev client)
+npx expo prebuild                      # Generate native projects
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Pod install fails | `cd ios && bundle exec pod install --repo-update` |
+| Xcode build fails | `cd ios && xcodebuild clean` |
+| Android Gradle sync fails | Open Android Studio sync details, then run the failing Gradle task directly |
+| Can't find simulator | `xcrun simctl list` to verify name |
+| Metro cache issues | `npx react-native start --reset-cache` |
+| React Native cache issues | Clear the specific cache reported by the failing tool |
+
+## Related Skills
+
+- [native-profiling.md](./native-profiling.md) - Use IDE profilers
+- [native-turbo-modules.md](./native-turbo-modules.md) - Build native modules
+- [upgrading-react-native.md](../../upgrading-react-native/references/upgrading-react-native.md) - Upgrade React Native safely

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-profiling.md

@@ -0,0 +1,140 @@
+---
+title: Profile Native Code
+impact: MEDIUM
+tags: xcode, instruments, android-studio, profiler
+---
+
+# Skill: Profile Native Code
+
+Use Xcode Instruments and Android Studio Profiler to identify native performance bottlenecks.
+
+## Quick Command
+
+```bash
+# iOS: Open Instruments
+# Xcode → Open Developer Tool → Instruments → Time Profiler
+
+# Android: Open Profiler
+# Android Studio → View → Tool Windows → Profiler
+```
+
+## When to Use
+
+- App is slow but JS profiler shows no issues
+- Investigating native module performance
+- Startup feels slow (native init)
+- Battery drain concerns
+- Need CPU/memory breakdown by thread
+
+> **Note**: This skill involves visual profiler output (Xcode Instruments, Android Studio Profiler). Use `agent-device` for runnable app evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. Profiler-specific GUI analysis may still require exported traces or human review. Record concrete thread names, stack frames, and durations in text when asking an agent to reason about them.
+
+## iOS Profiling with Xcode
+
+### Quick Check: Debug Navigator
+
+Use Xcode's Debug Navigator for quick CPU, memory, disk, and network signals before collecting a full Instruments trace.
+
+**CPU percentage can exceed 100%** (multi-core usage).
+
+### Deep Profiling: Instruments
+
+Record a Time Profiler trace on the target device, perform the suspect interaction, and inspect the relevant threads and call stacks.
+
+### Analyzing Time Profiler Results
+
+**Key views:**
+- **Flame Graph**: Visual call stack over time
+- **Call Tree**: Hierarchical function breakdown
+- **Ranked**: Functions sorted by time (Bottom-Up)
+
+**Useful filters:**
+- Hide System Libraries
+- Invert Call Tree (bottom-up view)
+- Filter by thread (main, JS, etc.)
+
+**Identifying problems:**
+- **Microhang**: Brief UI unresponsiveness
+- **Hang**: Full UI thread block (critical)
+- Yellow = most time spent
+
+### Thread Breakdown
+
+Pin threads to compare:
+- **Main thread** (SampleApp): UI rendering
+- **JavaScript thread**: React/JS execution
+- **Background threads**: Native modules
+
+JS thread blocking and UI thread blocking are different signals; inspect both before choosing a fix.
+
+## Android Profiling with Android Studio
+
+### Launch Profiler
+
+Use Android Studio Profiler on the target device or emulator.
+
+### CPU Profiling
+
+Record CPU hotspots while performing the suspect interaction, then inspect flame graph, bottom-up, and timeline views.
+
+### Analyzing Results
+
+**Flame Graph:**
+- Zoom with scroll/pinch
+- Click to expand call stacks
+- Filter by keyword (e.g., "hermes")
+
+**Views:**
+- **Top Down**: From entry points down
+- **Bottom Up**: From slowest functions up
+- **Flame Chart**: Timeline visualization
+
+### Reading the Call Stack
+
+Example analysis:
+```
+JS Thread activity after button press:
+- Event handler on main thread
+- Triggers JS work via sync JSI calls
+- Hermes processes React reconciliation
+- Significant time in commit/layout-related work
+```
+
+## Platform Tools Summary
+
+| Tool | Platform | Use Case |
+|------|----------|----------|
+| Time Profiler | iOS | CPU hotspots |
+| Leaks | iOS | Memory leaks |
+| Hangs | iOS | UI thread blocks |
+| CPU Profiler | Android | CPU hotspots |
+| Memory Profiler | Android | Memory tracking |
+| Perfetto | Android | Advanced trace analysis |
+
+## Perfetto (Advanced Android)
+
+Export traces from Android Studio and analyze at [ui.perfetto.dev](https://ui.perfetto.dev/):
+
+- Cross-process analysis
+- Custom trace events
+- Additional visualizations
+
+## Expo Notes
+
+- **Expo Go**: Cannot profile native code directly; JS profiling only
+- **Dev Client / Prebuild**: Full native profiling supported via Xcode/Android Studio
+- Run `npx expo prebuild` to generate native projects, then profile as bare React Native
+
+## Common Findings
+
+| Symptom | Likely Cause |
+|---------|--------------|
+| Main thread hangs | Heavy UI work, blocked operations |
+| JS thread spikes | React re-renders, heavy computation |
+| Background thread busy | Native module work |
+| Memory climbing | Leak (see memory profiling skills) |
+
+## Related Skills
+
+- [native-measure-tti.md](./native-measure-tti.md) - Profile startup specifically
+- [native-memory-leaks.md](./native-memory-leaks.md) - Memory profiling
+- [js-profile-react.md](./js-profile-react.md) - JS/React profiling

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-sdks-over-polyfills.md

@@ -0,0 +1,192 @@
+---
+title: Native SDKs
+impact: HIGH
+tags: polyfills, intl, crypto, navigation, native
+---
+
+# Skill: Native SDKs
+
+Replace web polyfills and JS navigators with native React Native implementations for better performance.
+
+## Quick Pattern
+
+**Before (JS polyfills - 430+ KB):**
+
+```tsx
+import '@formatjs/intl-datetimeformat/polyfill';
+import CryptoJS from 'crypto-js';
+import { createStackNavigator } from '@react-navigation/stack';
+```
+
+**After (native implementations):**
+
+```tsx
+// Keep this polyfill only if the app uses DateTimeFormat options/locales
+// unsupported by the target Hermes/platform combination.
+import { createHash } from 'react-native-quick-crypto';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+```
+
+## When to Use
+
+- Large JS bundle from polyfills
+- Navigation feels non-native
+- Crypto operations are slow
+- Internationalization bloating bundle
+
+## Step-by-Step Instructions
+
+### 1. Remove Unnecessary Intl Polyfills
+
+Hermes supports many `Intl` APIs natively, but not every constructor and method combination across platforms. Audit the exact APIs and methods you use before removing polyfills:
+
+```tsx
+// BEFORE: All these polyfills (430+ KB)
+import '@formatjs/intl-getcanonicallocales/polyfill';
+import '@formatjs/intl-locale/polyfill';
+import '@formatjs/intl-numberformat/polyfill';
+import '@formatjs/intl-numberformat/locale-data/en';
+import '@formatjs/intl-datetimeformat/polyfill';
+import '@formatjs/intl-datetimeformat/locale-data/en';
+import '@formatjs/intl-pluralrules/polyfill';
+import '@formatjs/intl-pluralrules/locale-data/en';
+import '@formatjs/intl-relativetimeformat/polyfill';
+import '@formatjs/intl-relativetimeformat/locale-data/en';
+import '@formatjs/intl-displaynames/polyfill';
+```
+
+**Hermes Intl support must be checked against the Hermes version in the app:**
+
+| API | Hermes | Keep Polyfill? |
+|-----|--------|----------------|
+| `Intl.Collator` | ✅ | No |
+| `Intl.DateTimeFormat` | ⚠️ Partial | Maybe |
+| `Intl.NumberFormat` | ⚠️ Partial | Maybe |
+| `Intl.getCanonicalLocales()` | ✅ | No |
+| `Intl.supportedValuesOf()` | ✅ | No |
+| `Intl.Locale` | ❌ | Yes |
+| `Intl.PluralRules` | ❌ | Yes |
+| `Intl.RelativeTimeFormat` | ❌ | Yes |
+| `Intl.DisplayNames` | ❌ | Yes |
+| `Intl.ListFormat` | ❌ | Yes |
+| `Intl.Segmenter` | ❌ | Yes |
+
+Constructor support does not guarantee every option or method your app uses. Keep polyfills for any API, option, locale data, or method the app depends on but Hermes does not fully support on the target platform.
+
+```tsx
+// AFTER: Keep only the polyfills your app still needs
+import '@formatjs/intl-locale/polyfill';
+import '@formatjs/intl-pluralrules/polyfill';
+import '@formatjs/intl-pluralrules/locale-data/en';
+import '@formatjs/intl-relativetimeformat/polyfill';
+import '@formatjs/intl-relativetimeformat/locale-data/en';
+import '@formatjs/intl-displaynames/polyfill';
+```
+
+If you use `Intl.NumberFormat.prototype.formatToParts()` on Hermes/iOS, also keep:
+
+```tsx
+import '@formatjs/intl-numberformat/polyfill';
+import '@formatjs/intl-numberformat/locale-data/en';
+```
+
+### 2. Use Native Crypto
+
+Replace JS crypto with native C++ implementation:
+
+```bash
+npm install react-native-quick-crypto
+```
+
+```tsx
+// BEFORE: Slow JS implementation
+import CryptoJS from 'crypto-js';
+
+// AFTER: Native C++ implementation
+import { createHash } from 'react-native-quick-crypto';
+```
+
+Essential for:
+- Web3 wallet seed generation
+- CSPRNG (Cryptographically Secure Random Numbers)
+- Any heavy cryptographic operations
+
+Benchmark crypto changes on the target device class. Native implementations usually reduce JS-thread work, but the exact win depends on algorithm, payload size, and bridge/JSI overhead.
+
+### 3. Use Native Stack Navigator
+
+```bash
+npm install @react-navigation/native-stack react-native-screens
+```
+
+```tsx
+// BEFORE: JS-based stack (more flexible, less native)
+import { createStackNavigator } from '@react-navigation/stack';
+const Stack = createStackNavigator();
+
+// AFTER: Native stack (native feel, better performance)
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+const Stack = createNativeStackNavigator();
+
+// Usage is nearly identical
+<Stack.Navigator>
+  <Stack.Screen name="Home" component={HomeScreen} />
+  <Stack.Screen name="Details" component={DetailsScreen} />
+</Stack.Navigator>
+```
+
+**Benefits:**
+- Native navigation animations
+- Platform-specific headers (large titles on iOS)
+- Lower memory usage
+- Offloads work from JS thread
+
+### 4. Use Native Bottom Tabs
+
+```bash
+npm install @bottom-tabs/react-navigation react-native-bottom-tabs
+```
+
+```tsx
+// BEFORE: JS tabs
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+const Tabs = createBottomTabNavigator();
+
+// AFTER: Native tabs
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation';
+const Tabs = createNativeBottomTabNavigator();
+
+<Tabs.Navigator>
+  <Tabs.Screen name="Home" component={HomeScreen} />
+  <Tabs.Screen name="Profile" component={ProfileScreen} />
+</Tabs.Navigator>
+```
+
+## Recommended Native Libraries
+
+| Category | Library | Description |
+|----------|---------|-------------|
+| Navigation | `react-native-screens` | Native screen containers |
+| Menus | `zeego` | Native menus (Radix-like API) |
+| Slider | `@react-native-community/slider` | Native slider |
+| Date Picker | `react-native-date-picker` | Native date/time picker |
+
+## Decision Matrix
+
+| Scenario | Use Native? | Tradeoff |
+|----------|-------------|----------|
+| Standard navigation | ✅ Yes | Slight API differences |
+| Custom transition animations | ⚠️ Maybe | Native is more limited |
+| Platform-consistent UI | ✅ Yes | Less customization |
+| Unique/branded design | ⚠️ Consider JS | Native may not support |
+
+## Common Pitfalls
+
+- **Assuming constructor support means full method coverage**: Check the specific Hermes API and methods you call
+- **Ignoring migration effort**: Native navigators have slightly different APIs
+- **Over-customizing native components**: If design requires heavy customization, JS might be better
+
+## Related Skills
+
+- [bundle-analyze-js.md](./bundle-analyze-js.md) - Measure polyfill impact
+- [bundle-library-size.md](./bundle-library-size.md) - Compare library sizes

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-threading-model.md

@@ -0,0 +1,230 @@
+---
+title: Threading Model
+impact: HIGH
+tags: threads, turbo-modules, fabric, async, sync
+---
+
+# Skill: Threading Model
+
+Understand which threads Turbo Modules and Fabric use for initialization, method calls, and view updates.
+
+## Quick Reference
+
+Thread names and exact scheduling can vary by React Native version, architecture, and host app setup. Use this as a default mental model, then confirm with a profiler when the exact thread matters.
+
+| Action | Default assumption |
+|--------|--------------------|
+| UI view creation/updates | Main/UI thread |
+| Sync value-returning Turbo Module method | Blocks the JS caller until it returns |
+| Async Turbo Module method | Does not block JS, but may run on a shared native modules executor |
+| Heavy CPU/I/O work | Move to a module-owned background queue/coroutine |
+
+**Key rule**: Sync methods should be trivial and deterministic. Move anything that can block, allocate heavily, perform I/O, or wait on locks to async/background work.
+
+## When to Use
+
+- Building native modules
+- Debugging threading issues
+- Accessing UI from native code
+- Understanding async vs sync method behavior
+
+## Available Threads
+
+| Thread | Name in Debugger | Purpose |
+|--------|------------------|---------|
+| Main/UI | Main thread | UI rendering, UIKit/Android Views |
+| JavaScript | `mqt_v_js` | JS execution, React |
+| Native Modules | `mqt_v_native` | Async Turbo Module calls |
+| Custom | Various | Your background threads |
+
+## Turbo Modules Threading
+
+### Initialization
+
+| Platform | Thread | Notes |
+|----------|--------|-------|
+| iOS | Main thread | Assumes UIKit access needed |
+| Android (lazy) | JS thread | Default behavior |
+| Android (eager) | Native modules thread | When `needsEagerInit = true` |
+
+**iOS**: React Native runs `init` on main thread assuming UIKit access.
+
+**Android Eager Loading:**
+
+```kotlin
+// ReactModuleInfo constructor params:
+// canOverrideExistingModule, needsEagerInit, isCxxModule, isTurboModule
+ReactModuleInfo(
+    AwesomeModule.NAME,
+    AwesomeModule.NAME,
+    false,
+    true,   // needsEagerInit = true → runs on native modules thread
+    false,
+    true
+)
+```
+
+### Synchronous Method Calls
+
+Synchronous value-returning Turbo Module methods block the JS caller until they return. Treat them as JS-critical even if a platform implementation dispatches through an internal executor.
+
+```swift
+// iOS - runs on JS thread
+@objc func multiply(_ a: Double, b: Double) -> NSNumber {
+    // This blocks JS for entire duration!
+    return a * b as NSNumber
+}
+```
+
+**Danger**: Long sync operations freeze the app:
+
+```swift
+// BAD: Blocks JS for 20 seconds
+@objc func multiply(_ a: Double, b: Double) -> NSNumber {
+    Thread.sleep(forTimeInterval: 20)  // App frozen!
+    return a * b as NSNumber
+}
+```
+
+### Asynchronous Method Calls
+
+**Usually dispatched off the JS thread** - does not block JS while the native work is pending.
+
+The native modules thread is shared across modules. If async work is CPU-heavy or long-running, move it to a module-owned queue/coroutine scope rather than occupying the shared React Native native modules thread.
+
+```swift
+// iOS - runs on mqt_v_native thread
+@objc func asyncOperation(
+    _ a: Double,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: RCTPromiseRejectBlock
+) {
+    // Already on background thread
+    resolve(a * 2)
+}
+```
+
+```kotlin
+// Android - runs on native modules thread
+override fun asyncOperation(a: Double, promise: Promise?) {
+    // Already on background thread
+    promise?.resolve(a * 2)
+}
+```
+
+### Module Invalidation
+
+Called when React Native instance is torn down (e.g., Metro reload):
+
+| Platform | Thread |
+|----------|--------|
+| iOS | Native modules thread |
+| Android | ReactHost thread pool |
+
+**iOS**: Implement `RCTInvalidating` protocol.
+
+## Fabric (Native Views) Threading
+
+### View Lifecycle
+
+| Operation | Default assumption |
+|-----------|--------------------|
+| View init | Main thread |
+| Prop updates | Main thread |
+| Layout/shadow tree work | Architecture-dependent; profile before assuming thread ownership |
+
+Views always manipulate UI on main thread (UIKit/Android requirement).
+
+Do not use a hard-coded "Yoga runs on X thread" rule when diagnosing performance. React Native's renderer and scheduler details change across New Architecture releases; use Instruments, Perfetto, or Android Studio profiler to identify the actual bottleneck.
+
+## Moving Work to Background
+
+### iOS: DispatchQueue
+
+```swift
+@objc func heavyWork(
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: RCTPromiseRejectBlock
+) {
+    DispatchQueue.global().async {
+        // Heavy computation here
+        let result = self.compute()
+        resolve(result)
+    }
+}
+```
+
+### Android: Coroutines
+
+```kotlin
+class MyModule(reactContext: ReactApplicationContext) :
+    NativeMyModuleSpec(reactContext) {
+    
+    private val moduleScope = CoroutineScope(Dispatchers.Default + SupervisorJob())
+    
+    override fun heavyWork(promise: Promise?) {
+        moduleScope.launch {
+            // Heavy computation here
+            val result = compute()
+            promise?.resolve(result)
+        }
+    }
+    
+    override fun invalidate() {
+        super.invalidate()
+        moduleScope.cancel()  // Important: cancel to prevent leaks
+    }
+}
+```
+
+## Thread Safety Checklist
+
+| Scenario | Safe? | Solution |
+|----------|-------|----------|
+| Sync method accessing shared state | ⚠️ | Use locks/synchronized |
+| Async method accessing UI | ❌ | Dispatch to main thread |
+| Multiple async calls to same resource | ⚠️ | Queue or mutex |
+| Accessing JS from background | ❌ | Use CallInvoker |
+
+### Accessing UI from Background (iOS)
+
+```swift
+DispatchQueue.global().async {
+    let result = self.heavyComputation()
+    
+    DispatchQueue.main.async {
+        // Safe to update UI here
+        self.updateUI(with: result)
+    }
+}
+```
+
+### Accessing UI from Background (Android)
+
+```kotlin
+moduleScope.launch(Dispatchers.Default) {
+    val result = heavyComputation()
+    
+    withContext(Dispatchers.Main) {
+        // Safe to update UI here
+        updateUI(result)
+    }
+}
+```
+
+## Summary Table
+
+| Action | iOS Thread | Android Thread |
+|--------|------------|----------------|
+| Module init | Version/setup dependent; avoid blocking | Version/setup dependent; avoid blocking |
+| Sync method | Blocks JS caller | Blocks JS caller |
+| Async method | Shared native executor or implementation-defined | Shared native executor or implementation-defined |
+| View init | Main | Main |
+| Prop update | Main | Main |
+| Yoga/layout | Profile; do not assume fixed ownership | Profile; do not assume fixed ownership |
+| Invalidate | Native modules | ReactHost pool |
+
+## Related Skills
+
+- [native-turbo-modules.md](./native-turbo-modules.md) - Implement background threads
+- [native-profiling.md](./native-profiling.md) - Debug thread issues