React Native KnotAPI

Please see https://docs.knotapi.com/ for installation instructions.

🚨 Critical Bridge Fixes

This version includes critical fixes to prevent crashes in React Native applications, specifically addressing bridge teardown race conditions and memory management issues.

Quick Fix Summary

• Bridge State Management: Added lifecycle tracking to prevent events being sent to deallocated bridges
• Close Protection: Prevents multiple close calls and double teardown scenarios
• Delegate Safety: All delegate methods now safely ignore events when bridge is inactive
• Exception Handling: Graceful handling of exceptions during close operations
• Memory Management: Proper cleanup and weak reference patterns

Crash Scenarios Fixed

• ✅ Bridge teardown race conditions
• ✅ Events sent to deallocated bridge
• ✅ Multiple close() calls causing double teardown
• ✅ Memory leaks and retain cycles
• ✅ Exception handling during close operations

Required iOS SDK Fix

CRITICAL: The iOS SDK must also be updated to make KnotSession.delegate a weak reference:

// In KnotSession.swift - REQUIRED FIX
public weak var delegate: KnotEventDelegate?

Testing

Comprehensive test suite included to verify all crash scenarios are handled:

cd ios/
./run_tests.sh

Test Options:

• Simple Tests (No Xcode required) - Quick verification of all fixes
• Full XCTest Suite - Comprehensive testing with mocking and edge cases
• Crash Scenario Tests - Specific tests for crash prevention

GitHub Actions Integration

Automated testing with GitHub Actions:

• CI (.github/workflows/ci.yml) - Runs on PRs to main: TypeScript type checking, ESLint, and Jest tests
• Bridge Tests (.github/workflows/test.yml) - Runs on push/PR/release for iOS bridge testing
• Conditional Testing - Additional tests run on releases (iOS compatibility, documentation)

📚 Technical Details

Bridge Fixes Implementation

Files Modified:

• ios/Knotapi.mm - Core bridge implementation with safety checks

Key Changes:

// Added properties
@property (nonatomic, assign) BOOL isBridgeActive;
@property (nonatomic, assign) BOOL isClosing;

// Added safety checks to all delegate methods
- (void)onErrorWithError:(enum KnotError)error {
    if (!self.isBridgeActive) {
        NSLog(@"KnotAPI onError: Bridge inactive, ignoring event");
        return;
    }
    // ... rest of method
}

// Added close protection
- (void)close {
    if (self.isClosing) {
        NSLog(@"KnotAPI close: Already closing, ignoring duplicate call");
        return;
    }
    self.isClosing = YES;
    // ... rest of method
}

Test Suite

Test Files:

• ios/SimpleBridgeTest.m - Quick verification (no Xcode required)
• ios/KnotapiTests.m - Full XCTest suite
• ios/KnotapiCrashScenarioTests.m - Crash scenario tests
• ios/run_tests.sh - Comprehensive test runner (includes verification)

Running Tests:

cd ios/
./run_tests.sh

GitHub Actions

CI Workflow: .github/workflows/ci.yml

• Triggers: PRs to main
• Checks: TypeScript type checking, ESLint, Jest tests

Bridge Test Workflow: .github/workflows/test.yml

• Triggers: Push/PR/release/manual
• Tests: Bridge fixes, compilation, integration
• Conditional: iOS compatibility and docs on releases

Manual Testing:

gh workflow run test.yml

🔧 Troubleshooting

Running the Example App (iOS)

From the example/ directory:

# Install JS dependencies (from repo root first)
yarn install

# Install Ruby gems for CocoaPods
cd example
bundle install

# Run on iOS simulator / device
npm run ios

Prerequisites:

• Xcode 16.1+
• Node.js 18+ (installed via Homebrew or nvm)
• Ruby 3.3.4 (via rbenv — run rbenv install 3.3.4 if missing)
• CocoaPods (installed via bundle install inside example/)
• ios-deploy for physical device deployment: brew install ios-deploy

iOS Build Issues

Ruby Version / Bundler Mismatch

If npm run ios fails with:

Could not find 'bundler' (2.5.11) required by your Gemfile.lock

The example/ directory requires Ruby 3.3.4. A .ruby-version file is included to configure rbenv automatically.

Fix:

# Install Ruby 3.3.4 if not already available
rbenv install 3.3.4

# From the example/ directory, install gems
cd example
bundle install

Then retry npm run ios.

Node.js Path Issues (Xcode can't find Node)

If the build fails with:

/usr/local/bin/node: No such file or directory

This means example/ios/.xcode.env.local has a hardcoded Node path that doesn't match your installation (common when using Homebrew or nvm).

Fix — update .xcode.env.local:

echo 'export NODE_BINARY=$(command -v node)' > example/ios/.xcode.env.local

This makes Xcode dynamically resolve the Node binary instead of using a hardcoded path.

Physical Device Deployment — ios-deploy Missing

If the build succeeds but physical device installation fails with:

Failed to install the app on the device because we couldn't execute the "ios-deploy" command

Fix:

brew install ios-deploy

Test Files in Library Build

If you encounter errors like:

'XCTest/XCTest.h' file not found (in target 'react-native-knotapi' from project 'Pods')

Solution: The podspec has been updated to exclude test files from the main library build. If you're still seeing this error:

1. Clean your build:

   cd example/ios
   rm -rf build Pods Podfile.lock

2. Reinstall pods:

   bundle exec pod install

3. Try building again:

   cd ..
   npm run ios

General iOS Build Issues

If you encounter other iOS build issues:

1. Clean everything:

   cd example/ios
   rm -rf build Pods Podfile.lock
   cd ..
   rm -rf node_modules
   npm install
   bundle install
   cd ios
   bundle exec pod install

2. Check Xcode version compatibility:

   • Ensure you're using Xcode 16.1 or later
   • Verify iOS deployment target is 15.1+

3. Verify React Native setup:

   npx react-native doctor

Running the Example App (Android)

From the example/ directory:

npm run android

Prerequisites:

• Android Studio with Android SDK installed (default path: ~/Library/Android/sdk)
• ANDROID_HOME exported and platform-tools in your PATH
• An AVD (emulator) running or a physical device connected with USB debugging enabled

Add the following to your ~/.zshrc (or ~/.bash_profile) if not already present:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$PATH

Then reload your shell (source ~/.zshrc) and retry npm run android.

Android Build Issues

adb: command not found / App fails to launch

If the build succeeds but the app won't start:

/bin/sh: adb: command not found
spawnSync adb ENOENT

adb (Android Debug Bridge) is not in your PATH. The Android SDK is installed but the shell doesn't know where to find it.

Fix — add to ~/.zshrc:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$PATH

Reload with source ~/.zshrc, then retry.

No emulator or device found

If the CLI reports no devices:

Failed to launch emulator. Reason: No emulators found as an output of `emulator -list-avds`.

Fix:

• Open Android Studio → Device Manager → create or start an AVD, or
• Connect a physical Android device with USB debugging enabled

General Android build issues

1. Clean and rebuild:

   cd example/android
   ./gradlew clean
   cd ..
   npm run android

2. Verify React Native setup:

   npx react-native doctor

Installation & Usage

Please see https://docs.knotapi.com/ for complete installation and usage instructions.