@bcelep/capint 0.4.2 → 0.7.0

package/skills/react-native-best-practices/references/native-sdks-over-polyfills.md

@@ -0,0 +1,183 @@
+---
+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
+// Hermes has native Intl.DateTimeFormat - no polyfill needed
+import { createHash } from 'react-native-quick-crypto';  // 58x faster
+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 now supports many `Intl` APIs natively. Check your imports:
+
+```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 Support (as of 2025):**
+
+| API | Hermes | Keep Polyfill? |
+|-----|--------|----------------|
+| `Intl.Collator` | ✅ | No |
+| `Intl.DateTimeFormat` | ✅ | No |
+| `Intl.NumberFormat` | ✅ | No |
+| `Intl.getCanonicalLocales()` | ✅ | No |
+| `Intl.supportedValuesOf()` | ✅ | No |
+| `Intl.Locale` | ❌ | Yes |
+| `Intl.PluralRules` | ❌ | Yes |
+| `Intl.RelativeTimeFormat` | ❌ | Yes |
+| `Intl.DisplayNames` | ❌ | Yes |
+| `Intl.ListFormat` | ❌ | Yes |
+| `Intl.Segmenter` | ❌ | Yes |
+
+```tsx
+// AFTER: Only needed polyfills
+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';
+```
+
+### 2. Use Native Crypto
+
+Replace JS crypto with native C++ implementation:
+
+```bash
+npm install react-native-quick-crypto
+```
+
+**Performance**: Up to 58x faster than `crypto-js`.
+
+```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
+
+### 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 |
+| Image | `react-native-fast-image` | Native image caching |
+
+## 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 all polyfills needed**: Check Hermes compatibility first
+- **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/skills/react-native-best-practices/references/native-threading-model.md

@@ -0,0 +1,234 @@
+---
+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
+
+| Action | iOS Thread | Android Thread |
+|--------|------------|----------------|
+| Module init | Main | JS (lazy) / Native (eager) |
+| Sync method | JS | JS |
+| Async method | Native modules | Native modules |
+| View init/props | Main | Main |
+| Yoga layout | JS | JS |
+
+**Key rule**: Sync methods block JS thread. Keep under 16ms or make async.
+
+## 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
+
+**Always run on JS thread** - blocks until return.
+
+```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
+
+**Run on Native Modules thread** - doesn't block JS.
+
+```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 | Thread |
+|-----------|--------|
+| View init | Main thread |
+| Prop updates | Main thread |
+| Layout (Yoga) | JS thread |
+
+Views always manipulate UI on main thread (UIKit/Android requirement).
+
+### Yoga Layout
+
+Layout calculations happen on JS thread:
+
+```
+JS Thread: Calculate Yoga tree → Shadow tree
+Main Thread: Apply layout to native views
+```
+
+## 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 | Main | JS (lazy) / Native (eager) |
+| Sync method | JS | JS |
+| Async method | Native modules | Native modules |
+| View init | Main | Main |
+| Prop update | Main | Main |
+| Yoga layout | JS | JS |
+| 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

package/skills/react-native-best-practices/references/native-turbo-modules.md

@@ -0,0 +1,292 @@
+---
+title: Fast Native Modules
+impact: HIGH
+tags: turbo-modules, native, swift, kotlin, c++
+---
+
+# Skill: Fast Native Modules
+
+Build performant Turbo Modules using modern languages and background threading.
+
+## Quick Pattern
+
+**Incorrect (sync method blocks JS thread):**
+
+```swift
+@objc func heavyWork() -> NSNumber {
+    Thread.sleep(forTimeInterval: 2)  // Blocks JS for 2s!
+    return 42
+}
+```
+
+**Correct (async on background thread):**
+
+```swift
+@objc func heavyWork(
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: RCTPromiseRejectBlock
+) {
+    DispatchQueue.global().async {
+        let result = self.compute()
+        resolve(result)
+    }
+}
+```
+
+## When to Use
+
+- Creating new native modules
+- Optimizing existing module performance
+- Heavy computation needs to run off JS thread
+- Cross-platform C++ code needed
+
+## Prerequisites
+
+- React Native Builder Bob for scaffolding
+
+```bash
+npx create-react-native-library@latest my-library
+```
+
+## Step-by-Step Instructions
+
+### 1. Scaffold with Builder Bob
+
+```bash
+npx create-react-native-library@latest awesome-library
+# Follow prompts: choose Turbo Module, select languages
+```
+
+Creates ready-to-publish library with:
+- iOS (Obj-C/Swift) support
+- Android (Kotlin) support
+- TypeScript definitions
+- Codegen setup
+
+For local modules:
+
+```bash
+npx create-react-native-library@latest awesome-library --local
+```
+
+### 2. Enable Swift in iOS Module
+
+Update `awesome-library.podspec`:
+
+```diff
+- s.source_files = "ios/**/*.{h,m,mm,cpp}"
++ s.source_files = "ios/**/*.{h,m,mm,cpp,swift}"
+```
+
+Create Swift file in Xcode (accept bridging header prompt).
+
+Update header file for Swift compatibility:
+
+```objc
+// AwesomeLibrary.h
+#import <Foundation/Foundation.h>
+
+#if __cplusplus
+#import "ReactCodegen/RNAwesomeLibrarySpec/RNAwesomeLibrarySpec.h"
+#endif
+
+@interface AwesomeLibrary : NSObject
+#if __cplusplus
+<NativeAwesomeLibrarySpec>
+#endif
+@end
+```
+
+Import header in bridging header:
+
+```objc
+// AwesomeLibrary-Bridging-Header.h
+#import "AwesomeLibrary.h"
+```
+
+Implement in Swift:
+
+```swift
+// AwesomeLibrary.swift
+import Foundation
+
+extension AwesomeLibrary {
+    @objc func multiply(_ a: Double, b: Double) -> NSNumber {
+        return (a * b) as NSNumber
+    }
+}
+```
+
+Bridge in Obj-C++:
+
+```objc
+// AwesomeLibrary.mm
+#import "AwesomeLibrary.h"
+
+#if __has_include("awesome_library/awesome_library-Swift.h")
+#import "awesome_library/awesome_library-Swift.h"
+#else
+#import "awesome_library-Swift.h"
+#endif
+
+@implementation AwesomeLibrary
+RCT_EXPORT_MODULE()
+RCT_EXTERN_METHOD(multiply:(double)a b:(double)b);
+@end
+```
+
+### 3. Run on Background Thread (iOS)
+
+```swift
+@objc func heavyOperation(
+    _ input: Double,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: RCTPromiseRejectBlock
+) {
+    DispatchQueue.global().async {
+        // Heavy work on background thread
+        let result = self.expensiveComputation(input)
+        resolve(result)
+    }
+}
+```
+
+### 4. Run on Background Thread (Android)
+
+```kotlin
+class AwesomeLibraryModule(reactContext: ReactApplicationContext) :
+    NativeAwesomeLibrarySpec(reactContext) {
+    
+    private val moduleScope = CoroutineScope(Dispatchers.Default + SupervisorJob())
+    
+    override fun heavyOperation(input: Double, promise: Promise?) {
+        moduleScope.launch {
+            // Heavy work on coroutine
+            val result = expensiveComputation(input)
+            promise?.resolve(result)
+        }
+    }
+    
+    override fun invalidate() {
+        super.invalidate()
+        moduleScope.cancel()  // Prevent memory leaks!
+    }
+}
+```
+
+### 5. Use C++ for Cross-Platform Code
+
+Create C++ Turbo Module for shared logic:
+
+```cpp
+// MyCppModule.h
+#pragma once
+
+#include <ReactCommon/TurboModule.h>
+
+namespace facebook::react {
+
+class MyCppModule : public TurboModule {
+public:
+    MyCppModule(std::shared_ptr<CallInvoker> jsInvoker);
+    
+    double multiply(double a, double b);
+};
+
+} // namespace facebook::react
+```
+
+Register for iOS auto-linking:
+
+```objc
+// MyCppModuleRegistration.mm
+#include <ReactCommon/CxxTurboModuleUtils.h>
+
+@implementation MyCppModuleRegistration
+
++ (void)load {
+    facebook::react::registerCxxModuleToGlobalModuleMap(
+        std::string(facebook::react::MyCppModule::kModuleName),
+        [&](std::shared_ptr<facebook::react::CallInvoker> jsInvoker) {
+            return std::make_shared<facebook::react::MyCppModule>(jsInvoker);
+        }
+    );
+}
+
+@end
+```
+
+## Threading Summary
+
+| Method Type | Default Thread | Best Practice |
+|-------------|----------------|---------------|
+| Sync | JS thread | Keep fast (<16ms) |
+| Async | Native modules thread | OK for moderate work |
+| Heavy async | Custom background | Use DispatchQueue/Coroutines |
+
+## Language Interop Costs
+
+| Interface | Overhead | Notes |
+|-----------|----------|-------|
+| Obj-C ↔ C++ | ~0 | Compile-time |
+| Swift ↔ C++ | ~0 | Swift 5.9+ interop |
+| Kotlin ↔ C++ (JNI) | Medium | Per-call lookup |
+| C++ Turbo Module | Low | JSI direct access |
+
+**Tip**: C++ Turbo Modules skip JNI at runtime since JS holds direct C++ function references via JSI.
+
+## Code Example: Complete Async Operation
+
+```typescript
+// TypeScript interface
+export interface Spec extends TurboModule {
+    multiply(a: number, b: number): number;  // Sync
+    heavyOperation(input: number): Promise<number>;  // Async
+}
+```
+
+```kotlin
+// Android implementation
+override fun heavyOperation(input: Double, promise: Promise?) {
+    moduleScope.launch {
+        try {
+            val result = withContext(Dispatchers.Default) {
+                // Simulate heavy work
+                delay(1000)
+                input * 2
+            }
+            promise?.resolve(result)
+        } catch (e: Exception) {
+            promise?.reject("ERROR", e.message)
+        }
+    }
+}
+```
+
+```swift
+// iOS implementation
+@objc func heavyOperation(
+    _ input: Double,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+) {
+    DispatchQueue.global(qos: .userInitiated).async {
+        // Simulate heavy work
+        Thread.sleep(forTimeInterval: 1.0)
+        let result = input * 2
+        resolve(result)
+    }
+}
+```
+
+## Common Pitfalls
+
+- **Sync methods that block**: Keep under 16ms or make async
+- **Forgetting to cancel coroutine scope**: Causes memory leaks
+- **Not handling errors in async**: Always try/catch with reject
+- **Accessing UI from background**: Dispatch to main thread
+
+## Related Skills
+
+- [native-threading-model.md](./native-threading-model.md) - Thread details
+- [native-memory-patterns.md](./native-memory-patterns.md) - Memory in native code