objc-js 1.3.1 → 1.5.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

@@ -7,6 +7,37 @@ declare class NobjcObject {
     [key: string]: NobjcMethod;
     constructor(object: NobjcNative.ObjcObject);
 }
+export interface TypedBlockOptions {
+    /**
+     * Block return type encoding. Example: "v" (void), "@" (id), "B" (BOOL).
+     */
+    returns: string;
+    /**
+     * Block argument type encodings, excluding the implicit block-self (@?) parameter.
+     * Example: ["@", "Q", "^B"] for enumerateObjectsUsingBlock:.
+     */
+    args?: string[];
+    /**
+     * Full block type encoding. Example: "@?<v@?@Q^B>".
+     * When provided, this takes precedence over returns/args.
+     */
+    types?: string;
+}
+/**
+ * Attach an explicit block signature to a JavaScript function.
+ *
+ * Use this when Objective-C only exposes `@?` for a block parameter and
+ * objc-js would otherwise have to guess the callback argument types.
+ *
+ * @example
+ * ```typescript
+ * const handler = typedBlock({ returns: "v", args: ["@", "Q", "^B"] }, (obj, idx, stop) => {
+ *   console.log(obj.toString(), idx, stop);
+ * });
+ * array.enumerateObjectsUsingBlock$(handler);
+ * ```
+ */
+declare function typedBlock<T extends (...args: any[]) => any>(signature: string | TypedBlockOptions, fn: T): T;
 interface NobjcMethod {
     (...args: any[]): any;
 }
@@ -249,4 +280,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, typedBlock, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction } from "./native.js";
 const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
 const NATIVE_OBJC_OBJECT = Symbol("nativeObjcObject");
+const TYPED_BLOCK_ENCODING = "__nobjcBlockTypeEncoding";
 // WeakMap side-channel for O(1) proxy → native object lookup (bypasses Proxy traps)
 const nativeObjectMap = new WeakMap();
 // Module-scope Set for O(1) lookup instead of per-access array with O(n) .includes()
@@ -148,6 +149,44 @@ class NobjcObject {
         return proxy;
     }
 }
+function normalizeTypedBlockEncoding(signature) {
+    if (typeof signature === "string") {
+        if (!signature.startsWith("@?")) {
+            throw new TypeError("typedBlock(string, fn) expects a full block type encoding starting with '@?'");
+        }
+        return signature;
+    }
+    if (signature.types !== undefined) {
+        if (!signature.types.startsWith("@?")) {
+            throw new TypeError("typedBlock({ types }, fn) expects a full block type encoding starting with '@?'");
+        }
+        return signature.types;
+    }
+    const args = signature.args ?? [];
+    return `@?<${signature.returns}@?${args.join("")}>`;
+}
+/**
+ * Attach an explicit block signature to a JavaScript function.
+ *
+ * Use this when Objective-C only exposes `@?` for a block parameter and
+ * objc-js would otherwise have to guess the callback argument types.
+ *
+ * @example
+ * ```typescript
+ * const handler = typedBlock({ returns: "v", args: ["@", "Q", "^B"] }, (obj, idx, stop) => {
+ *   console.log(obj.toString(), idx, stop);
+ * });
+ * array.enumerateObjectsUsingBlock$(handler);
+ * ```
+ */
+function typedBlock(signature, fn) {
+    Object.defineProperty(fn, TYPED_BLOCK_ENCODING, {
+        value: normalizeTypedBlockEncoding(signature),
+        enumerable: false,
+        configurable: true
+    });
+    return fn;
+}
 function unwrapArg(arg) {
     if (arg && typeof arg === "object") {
         return nativeObjectMap.get(arg) ?? arg;
@@ -161,6 +200,14 @@ function unwrapArg(arg) {
             }
             return unwrapArg(arg(...nativeArgs));
         };
+        const explicitBlockEncoding = arg[TYPED_BLOCK_ENCODING];
+        if (typeof explicitBlockEncoding === "string") {
+            Object.defineProperty(wrapped, TYPED_BLOCK_ENCODING, {
+                value: explicitBlockEncoding,
+                enumerable: false,
+                configurable: true
+            });
+        }
         // Preserve the original function's .length so the native layer can read it
         // (used to infer block parameter count when extended encoding is unavailable)
         Object.defineProperty(wrapped, "length", { value: arg.length });
@@ -605,4 +652,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, typedBlock, 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.1",
+  "version": "1.5.0",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "dependencies": {

package/src/native/ObjcObject.h

@@ -47,11 +47,17 @@ struct PreparedSend {
   std::vector<ArgInfo> argInfos;
 };
 
+struct NobjcEnvData {
+  Napi::FunctionReference objcObjectConstructor;
+};
+
 class ObjcObject : public Napi::ObjectWrap<ObjcObject> {
 public:
   __strong id objcObject;
-  static Napi::FunctionReference constructor;
   static void Init(Napi::Env env, Napi::Object exports);
+  static NobjcEnvData *GetEnvData(Napi::Env env);
+  static Napi::FunctionReference &GetConstructorRef(Napi::Env env);
+  static bool IsInstance(Napi::Env env, const Napi::Value &value);
   ObjcObject(const Napi::CallbackInfo &info)
       : Napi::ObjectWrap<ObjcObject>(info), objcObject(nil) {
     if (info.Length() == 1 && info[0].IsExternal()) {

package/src/native/ObjcObject.mm

@@ -311,7 +311,24 @@ struct ClassSELHash {
 static std::unordered_map<std::pair<Class, SEL>, NSMethodSignature *, ClassSELHash>
     methodSignatureCache;
 
-Napi::FunctionReference ObjcObject::constructor;
+NobjcEnvData *ObjcObject::GetEnvData(Napi::Env env) {
+  NobjcEnvData *data = env.GetInstanceData<NobjcEnvData>();
+  if (data == nullptr) {
+    throw Napi::Error::New(env, "objc-js addon state is not initialized");
+  }
+  return data;
+}
+
+Napi::FunctionReference &ObjcObject::GetConstructorRef(Napi::Env env) {
+  return GetEnvData(env)->objcObjectConstructor;
+}
+
+bool ObjcObject::IsInstance(Napi::Env env, const Napi::Value &value) {
+  if (!value.IsObject()) {
+    return false;
+  }
+  return value.As<Napi::Object>().InstanceOf(GetConstructorRef(env).Value());
+}
 
 void ObjcObject::Init(Napi::Env env, Napi::Object exports) {
   Napi::Function func =
@@ -323,8 +340,7 @@ void ObjcObject::Init(Napi::Env env, Napi::Object exports) {
                       InstanceMethod("$msgSendPrepared", &ObjcObject::$MsgSendPrepared),
                       InstanceMethod("$getPointer", &ObjcObject::GetPointer),
                   });
-  constructor = Napi::Persistent(func);
-  constructor.SuppressDestruct();
+  GetConstructorRef(env) = Napi::Persistent(func);
   exports.Set("ObjcObject", func);
 }
 
@@ -332,7 +348,8 @@ Napi::Object ObjcObject::NewInstance(Napi::Env env, id obj) {
   Napi::EscapableHandleScope scope(env);
   // `obj` is already a pointer, technically, but the Napi::External
   //  API expects a pointer, so we have to pointer to the pointer.
-  Napi::Object jsObj = constructor.New({Napi::External<id>::New(env, &obj)});
+  Napi::Object jsObj =
+      GetConstructorRef(env).New({Napi::External<id>::New(env, &obj)});
   return scope.Escape(jsObj).ToObject();
 }
 
@@ -442,10 +459,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 +518,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 +762,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 +815,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 +859,4 @@ Napi::Value ObjcObject::$MsgSendPrepared(const Napi::CallbackInfo &info) {
   }
 
   return ConvertReturnValueToJSValue(env, invocation, prepared->methodSignature);
-}
+}

package/src/native/bridge.h

@@ -181,7 +181,7 @@ T ConvertToNativeValue(const Napi::Value &value,
     // is value an ObjcObject instance?
     if (value.IsObject()) {
       Napi::Object obj = value.As<Napi::Object>();
-      if (obj.InstanceOf(ObjcObject::constructor.Value())) {
+      if (ObjcObject::IsInstance(value.Env(), obj)) {
         ObjcObject *objcObj = Napi::ObjectWrap<ObjcObject>::Unwrap(obj);
         return objcObj->objcObject;
       }

package/src/native/nobjc.mm

@@ -43,7 +43,7 @@ Napi::Value GetPointer(const Napi::CallbackInfo &info) {
   }
   
   Napi::Object obj = info[0].As<Napi::Object>();
-  if (!obj.InstanceOf(ObjcObject::constructor.Value())) {
+  if (!ObjcObject::IsInstance(env, obj)) {
     throw Napi::TypeError::New(env, "Argument must be an ObjcObject instance");
   }
   
@@ -79,7 +79,36 @@ 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);
+  }
+}
+
+static void CleanupEnvData(napi_env, void *data, void *) {
+  delete static_cast<NobjcEnvData *>(data);
+}
+
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
+  napi_set_instance_data(env, new NobjcEnvData(), CleanupEnvData, nullptr);
   ObjcObject::Init(env, exports);
   exports.Set("LoadLibrary", Napi::Function::New(env, LoadLibrary));
   exports.Set("GetClassObject", Napi::Function::New(env, GetClassObject));
@@ -90,6 +119,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,10 @@
 #include "type-conversion.h"
 #include "struct-utils.h"
 #include "ffi-utils.h"
+#include <Block.h>
 #include <Foundation/Foundation.h>
+#include <atomic>
+#include <dlfcn.h>
 #include <ffi.h>
 #include <napi.h>
 #include <objc/runtime.h>
@@ -51,10 +54,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 +72,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 +262,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,20 +298,27 @@ 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();
   }
 };
 
+constexpr const char *kTypedBlockEncodingProperty = "__nobjcBlockTypeEncoding";
+
 // MARK: - Block Call Data (transient, for cross-thread invocation)
 
 /**
@@ -321,15 +336,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)
 
@@ -344,7 +403,64 @@ static std::mutex g_blockRegistryMutex;
  * 1. Tagged pointers (arm64: high bit set) are always valid objects
  * 2. Use malloc_zone_from_ptr() to check if it's a heap allocation
  * 3. If it is, verify it has a valid class pointer
+ * 4. Fall back to image-backed singleton detection for constant objects like
+ *    __NSArray0 that live in the dyld shared cache instead of malloc heap
  */
+inline bool PointerResolvesToLoadedImage(const void *ptr) {
+  if (!ptr) return false;
+  Dl_info info;
+  return dladdr(ptr, &info) != 0;
+}
+
+inline uintptr_t GetObjCIsaClassMask() {
+  static uintptr_t mask = []() -> uintptr_t {
+    void *symbol = dlsym(RTLD_DEFAULT, "objc_debug_isa_class_mask");
+    if (symbol) {
+      return *static_cast<const uintptr_t *>(symbol);
+    }
+
+#if defined(__aarch64__) || defined(__arm64__)
+    return 0x0000000ffffffff8ULL;
+#elif defined(__x86_64__)
+    return 0x00007ffffffffff8ULL;
+#else
+    return 0;
+#endif
+  }();
+  return mask;
+}
+
+inline bool LooksLikeImageBackedObjCObject(uintptr_t val) {
+  void *ptr = reinterpret_cast<void *>(val);
+  if (!PointerResolvesToLoadedImage(ptr)) return false;
+
+  // Image-backed singleton objects (for example __NSArray0) are not malloc
+  // allocations, so inspect the isa word and see if it resolves to something
+  // that also looks like a class pointer in a loaded image.
+  uintptr_t isaBits = *reinterpret_cast<const uintptr_t *>(ptr);
+  if (isaBits < 4096) return false;
+
+  const uintptr_t isaMask = GetObjCIsaClassMask();
+  const uintptr_t isaCandidates[] = {
+      isaBits,
+      isaMask == 0 ? 0 : (isaBits & isaMask),
+  };
+
+  for (uintptr_t candidate : isaCandidates) {
+    if (candidate < 4096 || (candidate & (alignof(void *) - 1)) != 0) {
+      continue;
+    }
+
+    void *candidatePtr = reinterpret_cast<void *>(candidate);
+    if (malloc_zone_from_ptr(candidatePtr) ||
+        PointerResolvesToLoadedImage(candidatePtr)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 inline bool LooksLikeObjCObject(uintptr_t val) {
   if (val == 0) return false;  // nil
 
@@ -359,12 +475,14 @@ inline bool LooksLikeObjCObject(uintptr_t val) {
   // malloc_zone_from_ptr returns non-NULL only for valid heap allocations.
   void *ptr = (void *)val;
   malloc_zone_t *zone = malloc_zone_from_ptr(ptr);
-  if (!zone) return false;
+  if (zone) {
+    // It's a heap allocation — very likely an ObjC object.
+    // Do a final check: object_getClass should return a valid class.
+    Class cls = object_getClass((__bridge id)ptr);
+    if (cls != nil) return true;
+  }
 
-  // It's a heap allocation — very likely an ObjC object.
-  // Do a final check: object_getClass should return a valid class.
-  Class cls = object_getClass((__bridge id)ptr);
-  return cls != nil;
+  return LooksLikeImageBackedObjCObject(val);
 }
 
 /**
@@ -474,7 +592,7 @@ inline void SetBlockReturnFromJS(Napi::Value result, void *returnPtr,
       id objcVal = nil;
       if (result.IsObject()) {
         Napi::Object obj = result.As<Napi::Object>();
-        if (obj.InstanceOf(ObjcObject::constructor.Value())) {
+        if (ObjcObject::IsInstance(result.Env(), obj)) {
           ObjcObject *wrapper = Napi::ObjectWrap<ObjcObject>::Unwrap(obj);
           objcVal = wrapper->objcObject;
         }
@@ -547,6 +665,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 +688,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 +724,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 +743,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 +753,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;
     }
 
@@ -656,8 +780,22 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
                                      const char *typeEncoding) {
   NOBJC_LOG("CreateBlockFromJSFunction: encoding='%s'", typeEncoding);
 
+  std::string explicitTypeEncoding;
+  if (jsFunction.IsFunction()) {
+    Napi::Value encodingValue =
+        jsFunction.As<Napi::Function>().Get(kTypedBlockEncodingProperty);
+    if (encodingValue.IsString()) {
+      explicitTypeEncoding = encodingValue.As<Napi::String>().Utf8Value();
+      NOBJC_LOG("CreateBlockFromJSFunction: using explicit encoding='%s'",
+                explicitTypeEncoding.c_str());
+    }
+  }
+
+  const char *effectiveTypeEncoding =
+      explicitTypeEncoding.empty() ? typeEncoding : explicitTypeEncoding.c_str();
+
   // Parse the block signature
-  BlockSignature sig = ParseBlockSignature(typeEncoding);
+  BlockSignature sig = ParseBlockSignature(effectiveTypeEncoding);
   if (!sig.valid) {
     // No extended encoding — infer from JS function's .length
     // All params are treated as pointer-sized (heuristic detection in callback)
@@ -666,7 +804,7 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
 
     NOBJC_LOG("CreateBlockFromJSFunction: No extended block encoding, "
               "inferring %u params from JS function.length. Encoding: '%s'",
-              jsParamCount, typeEncoding);
+              jsParamCount, effectiveTypeEncoding);
 
     sig.returnType = "v";  // Assume void return
     sig.paramTypes.clear();
@@ -677,7 +815,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 +826,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 +876,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 +889,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 +900,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 +936,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;

package/src/native/subclass-impl.mm

@@ -279,7 +279,7 @@ Napi::Value DefineClass(const Napi::CallbackInfo &info) {
     }
   } else if (superValue.IsObject()) {
     Napi::Object superObj = superValue.As<Napi::Object>();
-    if (superObj.InstanceOf(ObjcObject::constructor.Value())) {
+    if (ObjcObject::IsInstance(env, superObj)) {
       ObjcObject *objcObj = Napi::ObjectWrap<ObjcObject>::Unwrap(superObj);
       superClass = (Class)objcObj->objcObject;
     }
@@ -627,7 +627,7 @@ Napi::Value CallSuper(const Napi::CallbackInfo &info) {
     throw Napi::TypeError::New(env, "First argument must be an ObjcObject (self)");
   }
   Napi::Object selfObj = info[0].As<Napi::Object>();
-  if (!selfObj.InstanceOf(ObjcObject::constructor.Value())) {
+  if (!ObjcObject::IsInstance(env, selfObj)) {
     throw Napi::TypeError::New(env, "First argument must be an ObjcObject (self)");
   }
   ObjcObject *selfWrapper = Napi::ObjectWrap<ObjcObject>::Unwrap(selfObj);

package/src/native/type-conversion.h

@@ -583,7 +583,7 @@ inline void SetInvocationReturnFromJS(NSInvocation *invocation,
   case '@': {
     if (result.IsObject()) {
       Napi::Object resultObj = result.As<Napi::Object>();
-      if (resultObj.InstanceOf(ObjcObject::constructor.Value())) {
+      if (ObjcObject::IsInstance(result.Env(), resultObj)) {
         ObjcObject *objcObj = Napi::ObjectWrap<ObjcObject>::Unwrap(resultObj);
         id objcValue = objcObj->objcObject;
         [invocation setReturnValue:&objcValue];