@maplibre/native-ffi

The low-level TypeScript binding for the MapLibre Native C API.

Every callback reaches the realm's event loop after the native call that raised it has returned, so native code answers each synchronous decision itself. A provider or transform request arrives as an owner that the host answers later.

Native code in the host can supply a wake or a queue lock as a native registration: Wake.native({ callback, userData, releaseUserData }) or QueueLock.native({ lock, unlock, userData, releaseUserData }), with each function pointer and the context as a bigint address. Native code calls a native wake directly, without a post to the realm. A queue lock has only this form, because native code relies on the lock being held when its callback returns. The first call that carries a native registration consumes it, and a later call throws a MaplibreError with the invalid-state status. Native code releases the context of a call that it accepts, and the binding calls the release for any other call.

A pending binding Promise keeps the process alive, and a callback registration or a wake does not. To wait for a callback, call the wake member of an AwaitableWake from it and await next().

A realm runs on one thread, so it can drive a caller-driven render session: make its context current on the JavaScript thread and call serviceDriverWork() when the driver-work wake arrives. A realm loads one copy of the binding.