@bcelep/capint 0.4.2 → 0.7.0

package/skills/react-native-best-practices/references/native-memory-patterns.md

@@ -0,0 +1,274 @@
+---
+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, C++ (smart ptrs) | Count refs, free at zero |
+| Garbage Collection | Kotlin/Java, JavaScript | GC scans and frees unreachable |
+| Manual | C, C++ (raw pointers) | Explicit new/delete |
+
+**Key rule**: Use `std::unique_ptr`/`std::shared_ptr` in C++, `weak` for delegates in Swift.
+
+## 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
+
+## Memory Management Patterns
+
+| Pattern | Languages | Mechanism |
+|---------|-----------|-----------|
+| Reference Counting | Swift, Obj-C, C++ (smart pointers) | Count refs, free at zero |
+| Garbage Collection | Kotlin/Java, JavaScript | GC scans and frees unreachable |
+| Manual | C, C++ (raw pointers) | Explicit new/delete |
+
+## 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
+
+### WeakHashMap for Caches
+
+```kotlin
+val weakMap = WeakHashMap<String, String>()
+
+run {
+    weakMap[String("temp")] = "value"
+    println(weakMap.size)  // 1
+}
+
+System.gc()  // Force garbage collection
+Thread.sleep(100)
+
+println(weakMap.size)  // 0 (key was collected)
+```
+
+### 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)
+
+For C interop, manually manage reference counts:
+
+```swift
+let obj = MyObject()                        // Ref count: 1
+
+// Increment manually
+let unmanaged = Unmanaged.passRetained(obj) // Ref count: 2
+
+// Decrement and get object
+let retrieved = unmanaged.takeRetainedValue() // Ref count: 1
+
+// Get raw pointer for C
+let pointer = unmanaged.toOpaque()
+```
+
+**Rule**: Match `passRetained` with `takeRetainedValue`, `passUnretained` with `takeUnretainedValue`.
+
+## Best Practices Summary
+
+| Language | Best Practice |
+|----------|---------------|
+| C++ | Use smart pointers (`shared_ptr`, `unique_ptr`) |
+| Swift | Use `weak` for delegates, breaking cycles |
+| 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

package/skills/react-native-best-practices/references/native-platform-setup.md

@@ -0,0 +1,110 @@
+---
+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 clean       # Clean Android build
+xed ios/                            # Open Xcode
+```
+
+## When to Use
+
+- Setting up native development environment
+- Adding native dependencies
+- Debugging platform-specific issues
+- Understanding build processes
+
+## Dependency Management
+
+### 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
+# Sync after adding dependencies
+cd android && ./gradlew clean
+
+# Key files
+android/build.gradle           # Project-level config
+android/app/build.gradle       # App dependencies
+android/gradle.properties      # Build flags
+android/gradlew                # Gradle wrapper
+```
+
+## 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
+npx react-native build-ios             # Build for iOS
+npx react-native build-android         # Build for 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 | `./gradlew clean` then sync |
+| Can't find simulator | `xcrun simctl list` to verify name |
+| Metro cache issues | `npx react-native start --reset-cache` |
+| React Native cache issues | `npx react-native clean` |
+
+## 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/skills/react-native-best-practices/references/native-profiling.md

@@ -0,0 +1,176 @@
+---
+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 interpreting visual profiler output (Xcode Instruments, Android Studio Profiler). AI agents cannot yet process screenshots autonomously. Use this as a guide while reviewing the profiler UI manually, or await MCP-based visual feedback integration (see roadmap).
+
+## iOS Profiling with Xcode
+
+### Quick Check: Debug Navigator
+
+1. Run app via Xcode
+2. Open Debug Navigator (side panel)
+3. View real-time: CPU, Memory, Disk, Network
+
+**CPU percentage can exceed 100%** (multi-core usage).
+
+### Deep Profiling: Instruments
+
+1. Open: **Xcode → Open Developer Tool → Instruments**
+2. Select **Time Profiler**
+3. Choose target device and app
+4. Click record (red circle)
+5. Perform actions in app
+6. Stop recording
+
+### 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
+
+**Pro tip**: JS thread blocking ≠ UI block (React Native design benefit).
+
+## Android Profiling with Android Studio
+
+### Launch Profiler
+
+1. **View → Tool Windows → Profiler**
+2. Or: Click "Profile" in toolbar
+
+### CPU Profiling
+
+1. Select **"Find CPU Hotspots"**
+2. Click **"Start profiler task"**
+3. Interact with app
+4. Stop to analyze
+
+### 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
+- ~30% time in "commit" phase (Yoga layout)
+```
+
+## Code Example: What to Look For
+
+### 5000 Views in ScrollView (Bad)
+
+Profiler shows:
+- 240ms+ JS thread work
+- Many 1ms Hermes spikes
+- Exceeds 16.6ms frame budget
+- Result: Dropped frames, UI jank
+
+### Using FlatList (Better)
+
+Profiler shows:
+- Minimal JS work (windowed rendering)
+- Smooth main thread
+- Stays within frame budget
+
+## 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
+
+## Pro Tips
+
+1. **Profile on low-end devices**: Issues appear more clearly
+2. **Use release builds**: Debug builds have overhead
+3. **Compare before/after**: Export traces for comparison
+4. **Filter by thread**: Focus on relevant work
+5. **Look for patterns**: Spikes correlating with interactions
+
+## 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