objc-js 1.3.0 → 1.4.0

package/README.md

@@ -37,6 +37,7 @@ The documentation is organized into several guides:
 - **[Structs](./docs/structs.md)** - Passing and receiving C structs (CGRect, NSRange, etc.)
 - **[Subclassing Objective-C Classes](./docs/subclassing.md)** - Creating and subclassing Objective-C classes from JavaScript
 - **[Blocks](./docs/blocks.md)** - Passing JavaScript functions as Objective-C blocks (closures)
+- **[Run Loop](./docs/run-loop.md)** - Pumping the CFRunLoop for async callback delivery (completion handlers, etc.)
 - **[Protocol Implementation](./docs/protocol-implementation.md)** - Creating delegate objects that implement protocols
 - **[API Reference](./docs/api-reference.md)** - Complete API documentation for all classes and functions
 
@@ -55,3 +56,46 @@ console.log(str.toString());
 ```
 
 For more examples and detailed guides, see the [documentation](./docs/basic-usage.md).
+
+## Companion Packages
+
+objc-js has two companion packages for TypeScript types and pure-C framework bindings:
+
+### objcjs-types
+
+Auto-generated TypeScript type definitions for macOS Objective-C frameworks. Provides IntelliSense and type checking for classes, protocols, enums, and methods across all major Apple frameworks.
+
+```bash
+npm install objcjs-types
+```
+
+```typescript
+import type { NSWindow, NSApplicationDelegate } from "objcjs-types/AppKit";
+import type { CGPoint, CGSize, CGRect } from "objcjs-types/structs";
+```
+
+### objcjs-extra
+
+Hand-written FFI bindings for macOS pure-C frameworks that have no Objective-C metadata (so they can't be auto-generated by objcjs-types). Works with both Bun (`bun:ffi`) and Node.js (`koffi`).
+
+```bash
+npm install objcjs-extra koffi    # Node.js
+bun add objcjs-extra              # Bun
+```
+
+Provides bindings for CoreFoundation, CoreGraphics, ApplicationServices (Accessibility), Security, CoreServices (FSEvents, Launch Services), IOKit, CoreText, ImageIO, CoreAudio, Network, CoreMedia, and Accelerate.
+
+```typescript
+import { AXUIElementCreateApplication, AXIsProcessTrusted } from "objcjs-extra/ApplicationServices";
+import { CGEventCreateKeyboardEvent, CGEventPost } from "objcjs-extra/CoreGraphics";
+import { getDefaultOutputDevice, setDeviceVolume } from "objcjs-extra/CoreAudio";
+import { preventSleep } from "objcjs-extra/IOKit";
+```
+
+### When to use which package
+
+| Need                                                                  | Package        |
+| --------------------------------------------------------------------- | -------------- |
+| Call Objective-C methods (NSWindow, NSString, etc.)                   | `objc-js`      |
+| TypeScript types for Objective-C APIs                                 | `objcjs-types` |
+| Pure-C frameworks (CoreFoundation, CoreGraphics, Accessibility, etc.) | `objcjs-extra` |

package/dist/index.d.ts

@@ -249,4 +249,52 @@ declare function callFunction(name: string, ...rest: any[]): any;
  * ```
  */
 declare function callVariadicFunction(name: string, ...rest: any[]): any;
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer, callFunction, callVariadicFunction };
+/**
+ * Utilities for pumping the macOS CFRunLoop from a Node.js/Bun event loop.
+ *
+ * Required for async Objective-C callbacks (completion handlers, AppKit events, etc.)
+ * to be delivered, since Node.js/Bun don't automatically pump the CFRunLoop.
+ *
+ * Usage:
+ *   RunLoop.run();   // Start pumping (returns a cleanup function)
+ *   RunLoop.pump();  // Pump once (non-blocking)
+ */
+declare const RunLoop: {
+    _timer: ReturnType<typeof setInterval> | null;
+    _mainRunLoop: any;
+    _defaultMode: any;
+    _NSDate: any;
+    /**
+     * Lazily initialise NSRunLoop and NSDefaultRunLoopMode references.
+     * Foundation is already loaded by the time any ObjC work happens, so
+     * GetClassObject will succeed without an explicit LoadLibrary call.
+     *
+     * We use proxy-wrapped NobjcObjects (via wrapObjCObjectIfNeeded) rather
+     * than raw native ObjcObjects + $msgSend, because Bun's N-API crashes
+     * when CFRunLoopRunInMode is triggered from the $msgSend C++ path.
+     * The proxy path ($prepareSend + $msgSendPrepared) works on both runtimes.
+     */
+    _ensureRunLoop(): void;
+    /**
+     * Pump the run loop once. Processes any pending run loop sources
+     * (AppKit events, dispatch_async to main queue, timers, etc.)
+     * without blocking.
+     *
+     * @param timeout Optional timeout in seconds (default: 0)
+     * @returns true if a source was processed
+     */
+    pump(timeout?: number): boolean;
+    /**
+     * Start continuously pumping the run loop on a regular interval.
+     * This enables async Objective-C callbacks to be delivered.
+     *
+     * @param intervalMs Pump interval in milliseconds (default: 10)
+     * @returns A cleanup function that stops pumping
+     */
+    run(intervalMs?: number): () => void;
+    /**
+     * Stop pumping the run loop.
+     */
+    stop(): void;
+};
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };

package/dist/index.js

@@ -32,7 +32,12 @@ class NobjcLibrary {
                     LoadLibrary(library);
                     this.wasLoaded = true;
                 }
-                cls = new NobjcObject(GetClassObject(className));
+                const classObject = GetClassObject(className);
+                if (classObject === undefined) {
+                    // Class not found. Make sure the class exists before trying to access it.
+                    return undefined;
+                }
+                cls = new NobjcObject(classObject);
                 classCache.set(className, cls);
                 return cls;
             }
@@ -55,6 +60,9 @@ class NobjcObject {
                 // Return true for the special Symbol to enable unwrapping
                 if (p === NATIVE_OBJC_OBJECT)
                     return true;
+                // Return true for inspect symbols so console.log uses custom inspect
+                if (p === customInspectSymbol)
+                    return true;
                 // guard against other symbols
                 if (typeof p === "symbol")
                     return Reflect.has(target, p);
@@ -117,6 +125,10 @@ class NobjcObject {
                     // object (avoids triggering proxy 'has' trap which would be a second FFI call)
                     const selector = NobjcMethodNameToObjcSelector(methodName);
                     if (!target.$respondsToSelector(selector)) {
+                        // special case since JS checks for `.then` on Promise objects
+                        if (methodName === "then")
+                            return undefined;
+                        // Otherwise, throw an error
                         throw new Error(`Method ${methodName} not found on object`);
                     }
                     method = NobjcMethod(object, methodName);
@@ -127,6 +139,9 @@ class NobjcObject {
         };
         // Create the proxy
         const proxy = new Proxy(object, handler);
+        // Set custom inspect on the native object so console.log works through the Proxy.
+        // Runtimes (Node, Bun) bypass Proxy traps during inspect and read the target directly.
+        object[customInspectSymbol] = () => proxy.toString();
         // Store proxy → native mapping in WeakMap for O(1) unwrap (bypasses Proxy traps)
         nativeObjectMap.set(proxy, object);
         // Return the proxy
@@ -590,4 +605,96 @@ function callVariadicFunction(name, ...rest) {
     const result = CallFunction(name, returnType, argTypes, fixedArgCount, ...args);
     return wrapObjCObjectIfNeeded(result);
 }
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer, callFunction, callVariadicFunction };
+/**
+ * Utilities for pumping the macOS CFRunLoop from a Node.js/Bun event loop.
+ *
+ * Required for async Objective-C callbacks (completion handlers, AppKit events, etc.)
+ * to be delivered, since Node.js/Bun don't automatically pump the CFRunLoop.
+ *
+ * Usage:
+ *   RunLoop.run();   // Start pumping (returns a cleanup function)
+ *   RunLoop.pump();  // Pump once (non-blocking)
+ */
+const RunLoop = {
+    _timer: null,
+    _mainRunLoop: null,
+    _defaultMode: null,
+    _NSDate: null,
+    /**
+     * Lazily initialise NSRunLoop and NSDefaultRunLoopMode references.
+     * Foundation is already loaded by the time any ObjC work happens, so
+     * GetClassObject will succeed without an explicit LoadLibrary call.
+     *
+     * We use proxy-wrapped NobjcObjects (via wrapObjCObjectIfNeeded) rather
+     * than raw native ObjcObjects + $msgSend, because Bun's N-API crashes
+     * when CFRunLoopRunInMode is triggered from the $msgSend C++ path.
+     * The proxy path ($prepareSend + $msgSendPrepared) works on both runtimes.
+     */
+    _ensureRunLoop() {
+        if (this._mainRunLoop === null) {
+            // Ensure Foundation is loaded — NobjcLibrary uses lazy loading,
+            // so Foundation may not be loaded yet if no class has been accessed.
+            LoadLibrary("/System/Library/Frameworks/Foundation.framework/Foundation");
+            const NSRunLoopRaw = GetClassObject("NSRunLoop");
+            if (!NSRunLoopRaw) {
+                throw new Error("Foundation framework is not loaded. Create a NobjcLibrary for Foundation before using RunLoop.");
+            }
+            const NSRunLoop = wrapObjCObjectIfNeeded(NSRunLoopRaw);
+            this._mainRunLoop = NSRunLoop.mainRunLoop();
+            const NSStringRaw = GetClassObject("NSString");
+            const NSString = wrapObjCObjectIfNeeded(NSStringRaw);
+            this._defaultMode = NSString.stringWithUTF8String$("kCFRunLoopDefaultMode");
+            const NSDateRaw = GetClassObject("NSDate");
+            this._NSDate = wrapObjCObjectIfNeeded(NSDateRaw);
+        }
+    },
+    /**
+     * Pump the run loop once. Processes any pending run loop sources
+     * (AppKit events, dispatch_async to main queue, timers, etc.)
+     * without blocking.
+     *
+     * @param timeout Optional timeout in seconds (default: 0)
+     * @returns true if a source was processed
+     */
+    pump(timeout) {
+        this._ensureRunLoop();
+        const limitDate = this._NSDate.dateWithTimeIntervalSinceNow$(timeout ?? 0);
+        const handled = this._mainRunLoop.runMode$beforeDate$(this._defaultMode, limitDate);
+        return !!handled;
+    },
+    /**
+     * Start continuously pumping the run loop on a regular interval.
+     * This enables async Objective-C callbacks to be delivered.
+     *
+     * @param intervalMs Pump interval in milliseconds (default: 10)
+     * @returns A cleanup function that stops pumping
+     */
+    run(intervalMs = 10) {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+        }
+        // Eagerly initialise so the first interval tick is cheap
+        this._ensureRunLoop();
+        this._timer = setInterval(() => {
+            const limitDate = this._NSDate.dateWithTimeIntervalSinceNow$(0);
+            this._mainRunLoop.runMode$beforeDate$(this._defaultMode, limitDate);
+        }, intervalMs);
+        // Unref the timer so it doesn't prevent the process from exiting
+        // when there are no other active handles
+        if (this._timer && typeof this._timer === "object" && "unref" in this._timer) {
+            this._timer.unref();
+        }
+        const stop = () => this.stop();
+        return stop;
+    },
+    /**
+     * Stop pumping the run loop.
+     */
+    stop() {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+};
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };

package/dist/native.d.ts

@@ -1,4 +1,4 @@
 import * as _binding from "#nobjc_native";
-declare const LoadLibrary: typeof _binding.LoadLibrary, GetClassObject: typeof _binding.GetClassObject, ObjcObject: typeof _binding.ObjcObject, GetPointer: typeof _binding.GetPointer, FromPointer: typeof _binding.FromPointer, CreateProtocolImplementation: typeof _binding.CreateProtocolImplementation, DefineClass: typeof _binding.DefineClass, CallSuper: typeof _binding.CallSuper, CallFunction: typeof _binding.CallFunction;
-export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction };
+declare const LoadLibrary: typeof _binding.LoadLibrary, GetClassObject: typeof _binding.GetClassObject, ObjcObject: typeof _binding.ObjcObject, GetPointer: typeof _binding.GetPointer, FromPointer: typeof _binding.FromPointer, CreateProtocolImplementation: typeof _binding.CreateProtocolImplementation, DefineClass: typeof _binding.DefineClass, CallSuper: typeof _binding.CallSuper, CallFunction: typeof _binding.CallFunction, PumpRunLoop: typeof _binding.PumpRunLoop;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction, PumpRunLoop };
 export type { _binding as NobjcNative };

package/dist/native.js

@@ -5,5 +5,5 @@ const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const binding = require("node-gyp-build")(join(__dirname, ".."));
-const { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction } = binding;
-export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction };
+const { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction, PumpRunLoop } = binding;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction, PumpRunLoop };

package/package.json

@@ -31,13 +31,14 @@
     "build": "npm run build-native && npm run build-scripts && npm run build-source",
     "pretest": "npm run build",
     "test": "bun run test:bun",
-    "test:bun": "bun run build && bun test",
-    "test:node": "bun run build && npx vitest run",
+    "test:bun": "bun test",
+    "test:node": "npx vitest run",
     "test:native": "bun test tests/test-native-code.test.ts",
     "test:js": "bun test tests/test-js-code.test.ts",
     "test:string-lifetime": "bun test tests/test-string-lifetime.test.ts",
     "test:object-arguments": "bun test tests/test-object-arguments.test.ts",
     "test:protocol-implementation": "bun test tests/test-protocol-implementation.test.ts",
+    "test:run-loop": "bun test tests/test-run-loop.test.ts",
     "bench": "bun run build && bun run benchmarks/bench.ts",
     "make-clangd-config": "node ./scripts/make-clangd-config.js",
     "format": "prettier --write \"**/*.{ts,js,json,md}\"",
@@ -46,7 +47,7 @@
     "prebuild:x64": "prebuildify --napi --strip --arch x64 -r node",
     "prebuild:all": "bun run prebuild:arm64 && bun run prebuild:x64"
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "dependencies": {

package/src/native/ObjcObject.h

@@ -4,11 +4,18 @@
 #include <napi.h>
 #include <objc/objc.h>
 #include <objc/runtime.h>
+#include <objc/message.h>
 #include <optional>
 #include <variant>
 #include <unordered_map>
 #include <vector>
 
+// objc_retain/objc_release are part of the stable ObjC ABI (macOS 10.12+)
+// but not declared in public headers. We use them for manual reference counting
+// since ARC is not enabled for .mm files in this project.
+extern "C" id objc_retain(id value);
+extern "C" void objc_release(id value);
+
 #ifdef __OBJC__
 @class NSMethodSignature;
 #else
@@ -51,6 +58,14 @@ public:
       // This better be an Napi::External<id>! We lost the type info at runtime.
       Napi::External<id> external = info[0].As<Napi::External<id>>();
       objcObject = *(external.Data());
+      // Retain the ObjC object so it stays alive as long as this JS wrapper
+      // exists. Without this, ARC/autorelease can deallocate the object while
+      // JS still holds a reference, causing Use-After-Free crashes (SIGTRAP)
+      // in completion handler callbacks and other async contexts.
+      // Note: ARC is not enabled for .mm files in this project (the -fobjc-arc
+      // flag is in OTHER_CFLAGS, not OTHER_CPLUSPLUSFLAGS), so __strong has
+      // no effect — we must manage retain/release manually.
+      if (objcObject) objc_retain(objcObject);
       return;
     }
     // If someone tries `new ObjcObject()` from JS, forbid it:
@@ -58,7 +73,12 @@ public:
         .ThrowAsJavaScriptException();
   }
   static Napi::Object NewInstance(Napi::Env env, id obj);
-  ~ObjcObject() = default;
+  ~ObjcObject() {
+    if (objcObject) {
+      objc_release(objcObject);
+      objcObject = nil;
+    }
+  }
 
 private:
   Napi::Value $MsgSend(const Napi::CallbackInfo &info);

package/src/native/ObjcObject.mm

@@ -442,10 +442,19 @@ Napi::Value ObjcObject::$MsgSend(const Napi::CallbackInfo &info) {
   constexpr size_t kSmallArgCount = 4;
   ObjcType smallArgBuf[kSmallArgCount];
   std::vector<ObjcType> heapArgBuf;
+  std::vector<id> createdBlocks;
   const bool useHeap = expectedArgCount > kSmallArgCount;
   if (useHeap) {
     heapArgBuf.reserve(expectedArgCount);
   }
+  createdBlocks.reserve(expectedArgCount);
+  [[maybe_unused]] auto releaseCreatedBlocks = MakeScopeGuard([&createdBlocks] {
+    for (id block : createdBlocks) {
+      if (block != nil) {
+        _Block_release(block);
+      }
+    }
+  });
 
   // Store struct argument buffers to keep them alive until after invoke.
   std::vector<std::vector<uint8_t>> structBuffers;
@@ -492,6 +501,7 @@ Napi::Value ObjcObject::$MsgSend(const Napi::CallbackInfo &info) {
       id block = CreateBlockFromJSFunction(env, info[i], blockEncoding);
       if (env.IsExceptionPending()) return env.Null();
       [invocation setArgument:&block atIndex:i + 1];
+      createdBlocks.push_back(block);
       // Store block as id in arg buffer to keep it alive until after invoke
       if (useHeap) {
         heapArgBuf.push_back(BaseObjcType{block});
@@ -735,10 +745,19 @@ Napi::Value ObjcObject::$MsgSendPrepared(const Napi::CallbackInfo &info) {
   constexpr size_t kSmallArgCount = 4;
   ObjcType smallArgBuf[kSmallArgCount];
   std::vector<ObjcType> heapArgBuf;
+  std::vector<id> createdBlocks;
   const bool useHeap = prepared->expectedArgCount > kSmallArgCount;
   if (useHeap) {
     heapArgBuf.reserve(prepared->expectedArgCount);
   }
+  createdBlocks.reserve(prepared->expectedArgCount);
+  [[maybe_unused]] auto releaseCreatedBlocks = MakeScopeGuard([&createdBlocks] {
+    for (id block : createdBlocks) {
+      if (block != nil) {
+        _Block_release(block);
+      }
+    }
+  });
 
   std::vector<std::vector<uint8_t>> structBuffers;
 
@@ -779,6 +798,7 @@ Napi::Value ObjcObject::$MsgSendPrepared(const Napi::CallbackInfo &info) {
       id block = CreateBlockFromJSFunction(env, info[jsArgIdx], blockEncoding);
       if (env.IsExceptionPending()) return env.Null();
       [invocation setArgument:&block atIndex:i + 2];
+      createdBlocks.push_back(block);
       if (useHeap) {
         heapArgBuf.push_back(BaseObjcType{block});
       } else {
@@ -822,4 +842,4 @@ Napi::Value ObjcObject::$MsgSendPrepared(const Napi::CallbackInfo &info) {
   }
 
   return ConvertReturnValueToJSValue(env, invocation, prepared->methodSignature);
-}
+}

package/src/native/nobjc.mm

@@ -79,6 +79,30 @@ Napi::Value FromPointer(const Napi::CallbackInfo &info) {
   return ObjcObject::NewInstance(env, reinterpret_cast<id>(ptr));
 }
 
+Napi::Value PumpRunLoop(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  
+  // Default timeout
+  NSTimeInterval timeout = 0.0;  // Don't block — just process pending sources
+  
+  // Optional: accept a timeout in seconds as the first argument
+  if (info.Length() >= 1 && info[0].IsNumber()) {
+    timeout = info[0].As<Napi::Number>().DoubleValue();
+  }
+  
+  // Pump the main run loop via NSRunLoop API.
+  // We use NSRunLoop instead of CFRunLoopRunInMode because the CF function
+  // crashes under Bun's N-API implementation (segfault in the CF call).
+  // NSRunLoop.runMode:beforeDate: is functionally equivalent and works
+  // correctly in both Node.js and Bun.
+  @autoreleasepool {
+    NSRunLoop *mainLoop = [NSRunLoop mainRunLoop];
+    NSDate *limitDate = [NSDate dateWithTimeIntervalSinceNow:timeout];
+    BOOL handled = [mainLoop runMode:NSDefaultRunLoopMode beforeDate:limitDate];
+    return Napi::Boolean::New(env, handled);
+  }
+}
+
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
   ObjcObject::Init(env, exports);
   exports.Set("LoadLibrary", Napi::Function::New(env, LoadLibrary));
@@ -90,6 +114,7 @@ Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
   exports.Set("DefineClass", Napi::Function::New(env, DefineClass));
   exports.Set("CallSuper", Napi::Function::New(env, CallSuper));
   exports.Set("CallFunction", Napi::Function::New(env, CallFunction));
+  exports.Set("PumpRunLoop", Napi::Function::New(env, PumpRunLoop));
   return exports;
 }
 

package/src/native/nobjc_block.h

@@ -37,7 +37,9 @@
 #include "type-conversion.h"
 #include "struct-utils.h"
 #include "ffi-utils.h"
+#include <Block.h>
 #include <Foundation/Foundation.h>
+#include <atomic>
 #include <ffi.h>
 #include <napi.h>
 #include <objc/runtime.h>
@@ -51,10 +53,14 @@
 
 // MARK: - Block ABI Structures
 
-// Block ABI descriptor (minimum viable — no copy/dispose helpers)
+struct BlockInfo;
+
+// Block ABI descriptor with copy/dispose helpers for BlockInfo lifetime.
 struct NobjcBlockDescriptor {
   unsigned long reserved;  // Always 0
   unsigned long size;      // sizeof(NobjcBlockLiteral)
+  void (*copy_helper)(void *dst, const void *src);
+  void (*dispose_helper)(const void *src);
 };
 
 // Block ABI literal struct
@@ -65,6 +71,7 @@ struct NobjcBlockLiteral {
   int reserved;            // Always 0
   void *invoke;            // Function pointer (FFI closure)
   NobjcBlockDescriptor *descriptor;
+  BlockInfo *blockInfo;    // Captured state retained/released by the block runtime
 };
 
 // _NSConcreteStackBlock is declared in <Block.h> (included via Foundation)
@@ -254,7 +261,7 @@ inline std::string GetExtendedBlockEncoding(Class cls, SEL selector, size_t argI
  * BlockInfo holds all state for a single JS-function-backed block.
  * It owns the FFI closure, CIF, arg types, JS function reference, and TSFN.
  *
- * Stored in a global registry for lifetime management (never freed in v1).
+ * Lifetime is tied to the Objective-C block copies plus any in-flight callbacks.
  */
 struct BlockInfo {
   // FFI closure and CIF
@@ -290,17 +297,22 @@ struct BlockInfo {
 
   // The heap-copied block (after _Block_copy)
   // Stored as void* since ARC is not enabled for .mm files in this project.
-  // The block is never freed in v1 (stored in global registry).
   void *heapBlock;
 
+  // One ref for the initially created block copy, plus one for each additional
+  // Objective-C block copy, plus one for each in-flight invocation.
+  std::atomic<size_t> refCount{1};
+
+  // Ensures we only release the TSFN's initial ref once.
+  std::atomic<bool> cleanupScheduled{false};
+
   ~BlockInfo() {
     // Free the FFI closure
     if (closure) {
       ffi_closure_free(closure);
       closure = nullptr;
     }
-    // Note: tsfn and jsFunction cleanup is tricky across threads.
-    // In v1, BlockInfo is never destroyed, so this is moot.
+    jsFunction.Reset();
   }
 };
 
@@ -321,15 +333,59 @@ struct BlockCallData {
   bool isComplete;
 };
 
-// MARK: - Global Block Registry
+// MARK: - Block Lifetime Management
 
-/**
- * Global registry of all created blocks.
- * Blocks are never freed in v1 — this prevents crashes from async callbacks
- * referencing freed memory.
- */
-static std::vector<std::unique_ptr<BlockInfo>> g_blockRegistry;
-static std::mutex g_blockRegistryMutex;
+constexpr int NOBJC_BLOCK_HAS_COPY_DISPOSE = (1 << 25);
+
+inline void RetainBlockInfo(BlockInfo *info) {
+  if (!info) return;
+  info->refCount.fetch_add(1, std::memory_order_relaxed);
+}
+
+inline void BlockTSFNFinalize(Napi::Env /*env*/, BlockInfo *info,
+                               BlockInfo * /*data*/) {
+  delete info;
+}
+
+inline void ScheduleBlockInfoCleanup(BlockInfo *info) {
+  if (!info) return;
+
+  bool expected = false;
+  if (!info->cleanupScheduled.compare_exchange_strong(
+          expected, true, std::memory_order_acq_rel)) {
+    return;
+  }
+
+  napi_status status = info->tsfn.Release();
+  if (status != napi_ok) {
+    NOBJC_ERROR("ScheduleBlockInfoCleanup: TSFN release failed (status=%d)", status);
+  }
+}
+
+inline void ReleaseBlockInfo(BlockInfo *info) {
+  if (!info) return;
+
+  size_t previous = info->refCount.fetch_sub(1, std::memory_order_acq_rel);
+  if (previous == 0) {
+    NOBJC_ERROR("ReleaseBlockInfo: refcount underflow");
+    return;
+  }
+  if (previous == 1) {
+    ScheduleBlockInfoCleanup(info);
+  }
+}
+
+inline void NobjcBlockCopyHelper(void *dst, const void *src) {
+  auto *dstBlock = static_cast<NobjcBlockLiteral *>(dst);
+  auto *srcBlock = static_cast<const NobjcBlockLiteral *>(src);
+  dstBlock->blockInfo = srcBlock->blockInfo;
+  RetainBlockInfo(dstBlock->blockInfo);
+}
+
+inline void NobjcBlockDisposeHelper(const void *src) {
+  auto *block = static_cast<const NobjcBlockLiteral *>(src);
+  ReleaseBlockInfo(block->blockInfo);
+}
 
 // MARK: - Block Argument Conversion (ObjC → JS)
 
@@ -547,6 +603,8 @@ inline void BlockTSFNCallback(Napi::Env env, Napi::Function /*jsCallback*/,
     callData->isComplete = true;
     callData->completionCv.notify_one();
   }
+
+  ReleaseBlockInfo(info);
 }
 
 // MARK: - FFI Closure Callback (Block Invoke)
@@ -568,6 +626,7 @@ inline void BlockInvokeCallback(ffi_cif *cif, void *ret, void **args,
     return;
   }
 
+  RetainBlockInfo(info);
   bool is_js_thread = pthread_equal(pthread_self(), info->js_thread);
 
   if (is_js_thread) {
@@ -603,6 +662,7 @@ inline void BlockInvokeCallback(ffi_cif *cif, void *ret, void **args,
         NOBJC_ERROR("BlockInvokeCallback: unknown exception");
       }
     }
+    ReleaseBlockInfo(info);
   } else {
     // Cross-thread call via TSFN
     BlockCallData callData;
@@ -621,6 +681,7 @@ inline void BlockInvokeCallback(ffi_cif *cif, void *ret, void **args,
     napi_status acq_status = info->tsfn.Acquire();
     if (acq_status != napi_ok) {
       NOBJC_ERROR("BlockInvokeCallback: Failed to acquire TSFN");
+      ReleaseBlockInfo(info);
       return;
     }
 
@@ -630,6 +691,7 @@ inline void BlockInvokeCallback(ffi_cif *cif, void *ret, void **args,
 
     if (status != napi_ok) {
       NOBJC_ERROR("BlockInvokeCallback: TSFN call failed (status=%d)", status);
+      ReleaseBlockInfo(info);
       return;
     }
 
@@ -677,7 +739,7 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
   }
 
   // Create BlockInfo
-  auto blockInfo = std::make_unique<BlockInfo>();
+  auto *blockInfo = new BlockInfo();
   blockInfo->signature = sig;
   blockInfo->env = env;
   blockInfo->js_thread = pthread_self();
@@ -688,8 +750,15 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
   blockInfo->jsFunction = Napi::Persistent(jsFunction.As<Napi::Function>());
 
   // Create TSFN for cross-thread calls
-  blockInfo->tsfn = CreateMethodTSFN(env, jsFunction.As<Napi::Function>(),
-                                     "nobjc_block_tsfn");
+  blockInfo->tsfn = Napi::ThreadSafeFunction::New(
+      env,
+      jsFunction.As<Napi::Function>(),
+      "nobjc_block_tsfn",
+      0,
+      1,
+      blockInfo,
+      BlockTSFNFinalize,
+      blockInfo);
 
   // Build FFI types for the block invocation
   // Block invoke signature: returnType (blockSelf, param1, param2, ...)
@@ -731,6 +800,7 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
   if (!blockInfo->closure || !codePtr) {
     Napi::Error::New(env, "Failed to allocate FFI closure for block")
         .ThrowAsJavaScriptException();
+    ReleaseBlockInfo(blockInfo);
     return nil;
   }
 
@@ -743,10 +813,9 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
       blockInfo->argFFIPtrs.data());
 
   if (ffiStatus != FFI_OK) {
-    ffi_closure_free(blockInfo->closure);
-    blockInfo->closure = nullptr;
     Napi::Error::New(env, "ffi_prep_cif failed for block")
         .ThrowAsJavaScriptException();
+    ReleaseBlockInfo(blockInfo);
     return nil;
   }
 
@@ -755,32 +824,35 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
       blockInfo->closure,
       &blockInfo->cif,
       BlockInvokeCallback,
-      blockInfo.get(),  // userdata = BlockInfo*
+      blockInfo,  // userdata = BlockInfo*
       codePtr);
 
   if (ffiStatus != FFI_OK) {
-    ffi_closure_free(blockInfo->closure);
-    blockInfo->closure = nullptr;
     Napi::Error::New(env, "ffi_prep_closure_loc failed for block")
         .ThrowAsJavaScriptException();
+    ReleaseBlockInfo(blockInfo);
     return nil;
   }
 
   // Build the block literal (stack block)
   blockInfo->descriptor.reserved = 0;
   blockInfo->descriptor.size = sizeof(NobjcBlockLiteral);
+  blockInfo->descriptor.copy_helper = NobjcBlockCopyHelper;
+  blockInfo->descriptor.dispose_helper = NobjcBlockDisposeHelper;
 
   blockInfo->blockLiteral.isa = _NSConcreteStackBlock;
-  blockInfo->blockLiteral.flags = (1 << 30);  // BLOCK_HAS_SIGNATURE (not strictly needed but harmless)
+  blockInfo->blockLiteral.flags = NOBJC_BLOCK_HAS_COPY_DISPOSE;
   blockInfo->blockLiteral.reserved = 0;
   blockInfo->blockLiteral.invoke = codePtr;
   blockInfo->blockLiteral.descriptor = &blockInfo->descriptor;
+  blockInfo->blockLiteral.blockInfo = blockInfo;
 
   // Copy to heap via _Block_copy
   void *heapBlockPtr = _Block_copy(&blockInfo->blockLiteral);
   if (!heapBlockPtr) {
     Napi::Error::New(env, "_Block_copy failed")
         .ThrowAsJavaScriptException();
+    ReleaseBlockInfo(blockInfo);
     return nil;
   }
 
@@ -788,12 +860,7 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
   blockInfo->heapBlock = heapBlockPtr;
 
   id result = (id)blockInfo->heapBlock;
-
-  // Store in global registry (never freed in v1)
-  {
-    std::lock_guard<std::mutex> lock(g_blockRegistryMutex);
-    g_blockRegistry.push_back(std::move(blockInfo));
-  }
+  ReleaseBlockInfo(blockInfo);
 
   NOBJC_LOG("CreateBlockFromJSFunction: created block %p", result);
   return result;