create-disposabl-app 0.1.0 → 0.1.2

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

@@ -0,0 +1,221 @@
+---
+title: Measure TTI (Time to Interactive)
+impact: HIGH
+tags: tti, startup, performance, markers
+---
+
+# Skill: Measure TTI (Time to Interactive)
+
+Set up performance markers to measure app startup time and track TTI improvements.
+
+## Quick Command
+
+```bash
+npm install react-native-performance
+```
+
+```tsx
+// Mark when screen is interactive
+import performance from 'react-native-performance';
+
+useEffect(() => {
+  performance.mark('screenInteractive');
+}, []);
+```
+
+## When to Use
+
+- App startup feels slow
+- Need baseline metrics for optimization
+- Setting up performance monitoring
+- Comparing TTI across releases
+
+## Prerequisites
+
+- `react-native-performance` library (recommended)
+
+> **Note**: This skill involves visual timeline diagrams and profiler output. Use `agent-device` for cold-start evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. Timeline interpretation may still require exported metrics or human review. Record concrete marker names, durations, device tier, and startup type in text when asking an agent to reason about them.
+
+## Understanding TTI
+
+**Time to Interactive**: Time from app icon tap to displaying usable content.
+
+### Startup Types
+
+| Type | Description | Measure? |
+|------|-------------|----------|
+| Cold | App not in memory, full init | ✅ Yes |
+| Warm | Process exists, activity recreated | ❌ Skip |
+| Hot | App in background, resumed | ❌ Skip |
+| Prewarmed (iOS) | iOS pre-initialized app | ❌ Filter out |
+
+**Only measure cold starts** for consistent metrics.
+
+## React Native Startup Pipeline
+
+**Pipeline markers:**
+```
+1. Native Process Init     (nativeLaunchStart → nativeLaunchEnd)
+2. Native App Init         (appCreationStart → appCreationEnd)  
+3. JS Bundle Load          (runJSBundleStart → runJSBundleEnd)
+4. RN Root View Render     (contentAppeared)
+5. React App Interactive   (screenInteractive) ← This is TTI
+```
+
+## Step-by-Step Implementation
+
+### 1. Detect Cold Start
+
+**iOS (Swift):**
+
+```swift
+let isColdStart = ProcessInfo.processInfo.environment["ActivePrewarm"] != "1"
+```
+
+**Android (Kotlin):**
+
+```kotlin
+class MainApplication : Application() {
+    var isColdStart = false
+    
+    override fun onCreate() {
+        super.onCreate()
+        
+        var firstPostEnqueued = true
+        Handler().post { firstPostEnqueued = false }
+        
+        registerActivityLifecycleCallbacks(object : ActivityLifecycleCallbacks {
+            override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {
+                unregisterActivityLifecycleCallbacks(this)
+                if (firstPostEnqueued && savedInstanceState == null) {
+                    isColdStart = true
+                }
+            }
+            // ... other callbacks
+        })
+    }
+}
+```
+
+### 2. Check Foreground State
+
+Only measure when app starts in foreground.
+
+**iOS:**
+
+```swift
+var isForegroundProcess = false
+
+override func application(_ application: UIApplication, 
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    if application.applicationState == .active {
+        isForegroundProcess = true
+    }
+    return true
+}
+```
+
+**Android:**
+
+```kotlin
+private fun isForegroundProcess(): Boolean {
+    val processInfo = ActivityManager.RunningAppProcessInfo()
+    ActivityManager.getMyMemoryState(processInfo)
+    return processInfo.importance == IMPORTANCE_FOREGROUND
+}
+```
+
+### 3. Set Up Performance Markers
+
+Using `react-native-performance`:
+
+**Native (iOS):**
+
+```swift
+import ReactNativePerformance
+
+RNPerformance.sharedInstance().mark("appCreationStart")
+// ... app init ...
+RNPerformance.sharedInstance().mark("appCreationEnd")
+```
+
+**Native (Android):**
+
+```kotlin
+import com.oblador.performance.RNPerformance
+
+RNPerformance.getInstance().mark("appCreationStart")
+// ... app init ...
+RNPerformance.getInstance().mark("appCreationEnd")
+```
+
+### 4. Mark Screen Interactive (JavaScript)
+
+```tsx
+import performance from 'react-native-performance';
+
+export default function HomeScreen() {
+    useEffect(() => {
+        // Mark when meaningful content is displayed
+        performance.mark('screenInteractive');
+    }, []);
+    
+    return <TabNavigator />;
+}
+```
+
+### 5. Collect and Report Metrics
+
+```tsx
+import performance from 'react-native-performance';
+
+const collectTTIMetrics = () => {
+    const entries = performance.getEntriesByType('mark');
+    
+    // Calculate durations
+    const metrics = {
+        nativeInit: getMarkDuration('nativeLaunchStart', 'nativeLaunchEnd'),
+        appCreation: getMarkDuration('appCreationStart', 'appCreationEnd'),
+        jsBundleLoad: getMarkDuration('runJSBundleStart', 'runJSBundleEnd'),
+        tti: getMarkDuration('nativeLaunchStart', 'screenInteractive'),
+    };
+    
+    // Send to analytics
+    analytics.track('app_performance', metrics);
+};
+```
+
+## Built-in Markers
+
+`react-native-performance` provides automatic markers:
+
+| Marker | Description |
+|--------|-------------|
+| `nativeLaunchStart` | Process start (pre-main) |
+| `nativeLaunchEnd` | Native init complete |
+| `runJSBundleStart` | JS bundle loading starts |
+| `runJSBundleEnd` | JS bundle loaded |
+| `contentAppeared` | RN root view rendered |
+
+`nativeLaunchStart` is pre-main and may include iOS prewarming. For prewarm-sensitive analysis, add a custom marker in `main()` and compare it with `nativeLaunchStart`.
+
+## Listening to Native Events
+
+Use the native marker APIs exposed by the app's React Native version to record JS bundle load and content-appeared milestones. Keep marker names consistent across iOS, Android, analytics, and test scripts.
+
+## Target Metrics
+
+Treat 2-4s as a broad external heuristic, not a universal target. Define app-specific targets by device tier, startup path, release build, and user/product metrics; optimize only against cold-start measurements filtered for warm, hot, prewarmed, and background launches.
+
+## Common Pitfalls
+
+- **Including prewarmed starts**: iOS prewarming skews metrics
+- **Measuring warm/hot starts**: Only cold starts are meaningful
+- **Wrong screenInteractive placement**: Mark when truly interactive, not just mounted
+- **Not filtering background launches**: Push notifications can start app in background
+
+## Related Skills
+
+- [bundle-analyze-js.md](./bundle-analyze-js.md) - Reduce JS bundle load time
+- [native-profiling.md](./native-profiling.md) - Profile native init
+- [bundle-hermes-mmap.md](./bundle-hermes-mmap.md) - Improve Android TTI

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

@@ -0,0 +1,206 @@
+---
+title: Hunt Native Memory Leaks
+impact: MEDIUM
+tags: memory, leaks, xcode, instruments, profiler
+---
+
+# Skill: Hunt Native Memory Leaks
+
+Find native memory leaks using Xcode Leaks and Android Studio Memory Profiler.
+
+## Quick Command
+
+```bash
+# iOS: Profile with Leaks instrument
+# Xcode → Product → Profile (Cmd+I) → Leaks template
+
+# Android: Memory Profiler
+# Android Studio → Run → Profile → Track Memory Consumption
+```
+
+## When to Use
+
+- App memory grows despite JS profiler showing no leaks
+- Native modules suspected of leaking
+- Activity recreation causes memory growth (Android)
+- C++/Swift/Kotlin code under investigation
+
+## iOS: Xcode Leaks
+
+### Quick Check: Memory Report
+
+1. Run app via Xcode
+2. Open **Debug Navigator** (side panel)
+3. Click **Memory**
+4. Watch graph for continuous growth
+
+### Deep Analysis: Instruments Leaks
+
+![Xcode Instruments Templates](images/xcode-instruments-templates.png)
+
+1. **Xcode → Product → Profile** (or Cmd+I)
+2. Select **Leaks** template (highlighted with orange triangle icon in the grid)
+3. Click **Choose**
+4. Click **Record** (red circle)
+5. Use the app, perform suspect actions
+6. Stop recording
+
+### Analyzing Results
+
+**Red markers** = Leaked memory detected
+
+Click on leak to see:
+- **Leaked Object**: Type and size
+- **Responsible Library**: Which code leaked
+- **Responsible Frame**: Exact function
+- **Stack Trace**: Full call path (right panel)
+
+Open the responsible frame to jump to source when symbols are available.
+
+### Common Native Leak: Missing Ownership
+
+```cpp
+void createNewStrings() {
+    auto str = std::make_unique<std::string>("Hello");
+}
+```
+
+Prefer RAII/smart pointers over raw `new`/`delete` in native module code.
+
+## Android: Memory Profiler
+
+### Launch Profiler
+
+Use Android Studio Memory Profiler and select a memory-consumption recording for the target process.
+
+### Recording
+
+1. Start the app
+2. Perform actions that might leak
+3. Watch memory graph for growth patterns
+
+### Analyzing Allocations
+
+Memory profiler shows:
+- **Allocations count**: Objects created
+- **Deallocations count**: Objects freed
+- **Live objects**: Still in memory
+
+If allocations greatly exceed deallocations after GC and after repeating the same flow, suspect a leak; confirm via retained objects, references, and lifecycle expectations.
+
+### LeakCanary (Android JVM Leaks)
+
+Use LeakCanary as a debug-only first line of defense for Android JVM leaks such as retained Activity/Context references, listeners, and coroutines that outlive a module. It does not see JS heap leaks or JSI/C++ Turbo Module leaks and can report React Native framework false positives.
+
+### Common Android Leak: Listener Not Removed
+
+```kotlin
+// BAD: Leaks MainActivity on config change
+class MainActivity : AppCompatActivity(), Callback {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        EventManager.addListener(this)
+        // Never removed!
+    }
+}
+
+// GOOD: Remove listener
+class MainActivity : AppCompatActivity(), Callback {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        EventManager.addListener(this)
+    }
+    
+    override fun onDestroy() {
+        EventManager.removeListener(this)
+        super.onDestroy()
+    }
+}
+```
+
+### Activity Recreation Test
+
+Repeat navigation and configuration-change flows, then check whether old activities or module instances are retained after GC.
+
+React Native note: RN opts out via `android:configChanges` in manifest, but native code might not.
+
+Use `agent-device` to repeat rotation/navigation scenarios, capture snapshots/screenshots, and collect device evidence. If it is missing and device verification is needed, install it through the environment's approved/trusted path or ask the user to install or enable it. Read the `agent-device` skill or CLI help when available before writing exact commands.
+
+## Debugging Workflow
+
+### iOS
+
+1. Profile with Instruments Leaks
+2. Trigger suspect actions repeatedly
+3. Wait for red leak markers
+4. Click to identify responsible frame
+5. Fix and re-test
+
+### Android
+
+1. Profile memory consumption
+2. Trigger suspect actions (rotate, navigate)
+3. Check allocation/deallocation counts
+4. Look for classes with 0 deallocations
+5. Fix and re-test
+
+## Code Fixes by Pattern
+
+### Reference Cycle (Swift)
+
+```swift
+// BAD
+class Parent {
+    var child: Child?
+}
+class Child {
+    var parent: Parent?  // Strong reference cycle
+}
+
+// GOOD
+class Parent {
+    var child: Child?
+}
+class Child {
+    weak var parent: Parent?  // Weak breaks cycle
+}
+```
+
+### Missing Cleanup (C++)
+
+```cpp
+// BAD
+void process() {
+    auto* data = new LargeData();
+    if (error) return;  // Leak!
+    delete data;
+}
+
+// GOOD: RAII with unique_ptr
+void process() {
+    auto data = std::make_unique<LargeData>();
+    if (error) return;  // Automatically cleaned up
+}
+```
+
+## Verification
+
+After fixing:
+1. Re-run profiler
+2. Perform same actions
+3. Verify:
+   - iOS: No red leak markers
+   - Android: Allocations return to a stable baseline after GC and repeated flows
+
+## Common Pitfalls
+
+- **Testing in debug mode**: Some leaks only appear in release
+- **Not waiting for GC**: Force GC before concluding no leak
+- **Ignoring small leaks**: They add up over time
+- **Missing cleanup in invalidate()**: Turbo Modules need proper cleanup
+
+## Related Skills
+
+- [native-memory-patterns.md](./native-memory-patterns.md) - Understanding memory patterns
+- [js-memory-leaks.md](./js-memory-leaks.md) - JS-side leaks
+- [native-threading-model.md](./native-threading-model.md) - Module invalidation

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

@@ -0,0 +1,240 @@
+---
+title: Native Memory Management
+impact: MEDIUM
+tags: memory, c++, swift, kotlin, arc, smart-pointers
+---
+
+# Skill: Native Memory Management
+
+Understand memory management patterns in C++, Swift, and Kotlin for React Native native modules.
+
+## Quick Reference
+
+| Pattern | Languages | Mechanism |
+|---------|-----------|-----------|
+| Reference Counting | Swift, Obj-C | Count refs, free at zero |
+| Smart pointers | C++ | Ownership encoded in pointer type |
+| Garbage Collection | Kotlin/Java, JavaScript | GC scans and frees unreachable |
+| Manual | C, C++ (raw pointers) | Explicit new/delete |
+
+**Key rule**: Prefer stack allocation or `std::unique_ptr` for single ownership; use `std::shared_ptr` only for real shared ownership and `std::weak_ptr` to break cycles. In Swift, use `weak` when the referenced object can disappear first; use `unowned` only when its lifetime is guaranteed to be at least as long.
+
+## When to Use
+
+- Writing native modules with manual memory management
+- Debugging native memory leaks
+- Interfacing C++ with Swift/Kotlin
+- Understanding reference counting vs garbage collection
+
+## C++ Smart Pointers
+
+### `std::unique_ptr` - Single Owner
+
+```cpp
+#include <memory>
+
+void takeOwnership(std::unique_ptr<std::string> s) {
+    std::cout << *s;
+    // Automatically deleted when function ends
+}
+
+int main() {
+    auto str = std::make_unique<std::string>("Hello");
+    
+    // Can only be moved, not copied
+    takeOwnership(std::move(str));
+    // str is now empty
+    
+    return 0;
+}
+```
+
+### `std::shared_ptr` - Multiple Owners
+
+```cpp
+void useShared(std::shared_ptr<std::string> s) {
+    std::cout << *s;  // Reference count temporarily +1
+}
+
+void useReference(const std::shared_ptr<std::string>& s) {
+    std::cout << *s;  // No ref count change (passed by reference)
+}
+
+int main() {
+    auto str = std::make_shared<std::string>("Hello");
+    
+    useShared(str);      // Copies pointer, ref count +1
+    useReference(str);   // No copy, ref count unchanged
+    
+    std::cout << *str;   // Still valid
+    return 0;
+}
+```
+
+### `std::weak_ptr` - Non-Owning Reference
+
+```cpp
+void useWeak(std::weak_ptr<std::string> weak) {
+    if (auto shared = weak.lock()) {  // Check if still exists
+        std::cout << *shared;
+    } else {
+        std::cout << "Object destroyed";
+    }
+}
+
+int main() {
+    auto str = std::make_shared<std::string>("Hello");
+    std::weak_ptr<std::string> weak = str;  // No ref count increase
+    
+    useWeak(weak);  // Works
+    str.reset();    // Destroys object
+    useWeak(weak);  // "Object destroyed"
+    
+    return 0;
+}
+```
+
+## Swift ARC (Automatic Reference Counting)
+
+```swift
+class Person {
+    let name: String
+    init(name: String) { self.name = name }
+    deinit { print("Deallocated") }
+}
+
+do {
+    let person1 = Person(name: "John")  // Ref count: 1
+    
+    do {
+        let person2 = person1  // Ref count: 2
+    }  // person2 out of scope, ref count: 1
+    
+}  // person1 out of scope, ref count: 0, "Deallocated"
+```
+
+### Breaking Reference Cycles with `weak`
+
+```swift
+// BAD: Reference cycle (memory leak)
+class A {
+    var b: B?
+}
+class B {
+    var a: A?  // Strong reference creates cycle
+}
+
+// GOOD: Use weak to break cycle
+class A {
+    var b: B?
+}
+class B {
+    weak var a: A?  // Weak reference, doesn't prevent deallocation
+}
+```
+
+## Kotlin/Android GC
+
+### Weak References for Caches
+
+`WeakHashMap` weakens keys, not values. Store `WeakReference` values explicitly when the cached value itself should not be strongly retained. Do not rely on deterministic `System.gc()` behavior in tests.
+
+### WeakReference for Callbacks
+
+```kotlin
+class DataManager {
+    // Weak references to listeners prevent memory leaks
+    private val listeners = mutableListOf<WeakReference<DataListener>>()
+    
+    fun addListener(listener: DataListener) {
+        listeners.add(WeakReference(listener))
+    }
+    
+    fun notifyListeners(data: String) {
+        listeners.forEach { ref ->
+            ref.get()?.onDataChanged(data)
+        }
+    }
+}
+```
+
+## Common Memory Leak Sources
+
+### 1. Forgetting to Delete (C++)
+
+```cpp
+// BAD: Memory leak
+int main() {
+    std::string* str = new std::string("Hello");
+    // Forgot to delete!
+    return 0;
+}
+
+// GOOD: Use smart pointers or stack allocation
+int main() {
+    auto str = std::make_unique<std::string>("Hello");
+    // Automatically deleted
+    return 0;
+}
+```
+
+### 2. Reference Cycles (Swift/C++)
+
+```cpp
+// BAD: Cycle
+class A { std::shared_ptr<B> b; };
+class B { std::shared_ptr<A> a; };
+
+// GOOD: Break with weak_ptr
+class A { std::shared_ptr<B> b; };
+class B { std::weak_ptr<A> a; };
+```
+
+### 3. Unremoved Listeners (Kotlin)
+
+```kotlin
+// BAD: Listener never removed
+class MyClass {
+    private val listener = object : Callback {
+        override fun onEvent() { /* ... */ }
+    }
+    
+    init {
+        EventManager.addListener(listener)
+        // Never removed!
+    }
+}
+
+// GOOD: Implement cleanup
+class MyClass : AutoCloseable {
+    private val listener = object : Callback {
+        override fun onEvent() { /* ... */ }
+    }
+    
+    init {
+        EventManager.addListener(listener)
+    }
+    
+    override fun close() {
+        EventManager.removeListener(listener)
+    }
+}
+```
+
+## Swift `Unmanaged` (Advanced)
+
+Use `Unmanaged` only for C interop that explicitly transfers ownership. Match `passRetained` with `takeRetainedValue`, and `passUnretained` with `takeUnretainedValue`.
+
+## Best Practices Summary
+
+| Language | Best Practice |
+|----------|---------------|
+| C++ | Prefer stack or `unique_ptr`; use `shared_ptr` only for shared ownership |
+| Swift | Use `weak` for delegates and disappearing references; use `unowned` only with guaranteed lifetime |
+| Kotlin | Implement `AutoCloseable`, use `WeakReference` |
+| All | Prefer stack over heap when possible |
+
+## Related Skills
+
+- [native-memory-leaks.md](./native-memory-leaks.md) - Find leaks with profilers
+- [native-turbo-modules.md](./native-turbo-modules.md) - Build memory-safe modules