bring execution model into the native core

.gitignore

@@ -35,3 +35,4 @@ bindings/openharmony/library/BuildProfile.ets
 .kotlin
 .devcontainer/mise-oci/
 .devcontainer/mise-oci.tar
+does-not-exist.db

.mise/bin/sync-submodules

@@ -56,7 +56,6 @@ mlt_vendor_paths=(
 # pointing at maplibre/maplibre-native. See patches/maplibre-native/README.md.
 mln_patches=(
   "$repo_root/patches/maplibre-native/0002-windows-local-file-urls.patch"
-  "$repo_root/patches/maplibre-native/0003-run-loop-process-gate.patch"
 )
 
 # A patch counts as applied when it reverses cleanly, which is also what makes

CMakePresets.json

@@ -542,6 +542,11 @@
       "configurePreset": "tvos-simulator-arm64-metal",
       "inherits": "_test-base"
     },
+    {
+      "name": "ohos-x64-egl",
+      "configurePreset": "ohos-x64-egl",
+      "inherits": "_test-base"
+    },
     {
       "name": "windows-x64-wgl",
       "configurePreset": "windows-x64-wgl",

Package.swift

@@ -30,7 +30,6 @@ let testSourceFiles = [
   "MaplibreNativeFFITests/SupportHelperTests.swift",
   "MaplibreNativeFFITests/SyntheticHandles.swift",
   "MaplibreNativeFFITests/ValueTests.swift",
-  "MaplibreNativeFFITests/WakeSourceTests.swift",
 ]
 
 let products: [Product] = [

bindings/dart/README.md

@@ -2,8 +2,8 @@
 
 `maplibre_native_ffi` is the low-level Dart binding for the public MapLibre
 Native C API. The package exposes explicit native handle lifetimes, copied value
-types, runtime event batches, resource callbacks, offline operations, and the
-render backend descriptors used by host integrations.
+types, owned runtime event batches, ordinary futures, resource callbacks, and
+the render backend descriptors used by host integrations.
 
 ## Build and test
 
@@ -30,6 +30,12 @@ native preset, and verifies that Flutter packages its code asset. Device and
 simulator iOS use separate presets because their dynamic libraries target
 different Apple SDKs.
 
+Use Metal or Vulkan for Dart on macOS. The macOS EGL target is temporarily
+excluded because the prebuilt ANGLE libraries do not have enough Mach-O header
+padding for Dart native assets to update their install names. The target can be
+enabled after the ANGLE libraries are relinked with
+`-headerpad_max_install_names` and the repository uses the new artifact.
+
 The native library reaches Dart as a code asset that `hook/build.dart` declares,
 which is how the generated `@Native` declarations resolve it. Build hooks run in
 a semi-hermetic environment that strips arbitrary environment variables, so the
@@ -69,40 +75,27 @@ copy of the same library.
 
 ## Ownership and execution
 
-Owned handles have an idempotent `close()` or `discard()` operation. Close child
-maps, render sessions, frames, snapshots, request handles, and offline
+Runtime and map handles have an idempotent `close()`. Runtime close remains
+asynchronous in Dart so callback roots stay alive through native teardown. Close
+child maps, render sessions, frames, snapshots, request handles, and offline
 operations before their parent runtime. Scoped backend values remain valid only
 until their frame or owner is closed.
 
-Runtime and map work is synchronous and owner-thread-affine. Keep a handle and
-all calls that use it on the isolate that created it. Run queued callbacks with
-`RuntimeHandle.pump()`, then take the events it produced with
-`RuntimeHandle.drainEvents()`. Narrow what a map or a runtime queues with
-`setEventMask`.
-
-A render session is the exception: it belongs to the isolate that attached it,
-which need not be the map's. A `MapHandle` cannot cross isolates, so
-`MapHandle.attachRef()` produces a `MapAttachRef` that can. It carries the
-native address and attaches; every other map call stays on the map's isolate.
-
-## Known draft deviation: do not await in an isolate that holds a handle
-
-The C API keys owner-thread checks on the OS thread. This binding keys them on
-`Isolate.current.hashCode`, and the two are not equivalent: the Dart VM moves an
-isolate between OS threads, and it does so when an isolate resumes from awaited
-I/O. The isolate hash does not change, so the binding's own check still passes
-while the native check starts failing.
-
-Until that is addressed, do not `await` I/O on an isolate that holds a runtime,
-map, projection, or render session. Create the handles, use them, and close them
-without yielding to I/O in between. Dart offers no equivalent of Go's
-`runtime.LockOSThread()`, so the binding cannot pin the isolate on your behalf.
-
-Exceeding this produces `wrongThread` from every call on the handle, including
-`close()`. Because close fails too, the native runtime is never destroyed and
-`mln_runtime_destroy` refuses for the rest of the process.
-
-Tracked in [#412](https://github.com/maplibre/maplibre-native-ffi/issues/412).
+Projection handles are created asynchronously and are synchronous after that:
+every projection call, `close()` included, runs on the calling isolate's thread,
+may be made from any isolate, and never observes map changes made after creation
+and remains usable after its source map and runtime close.
+
+Create runtimes and maps with `await`. Runtime and map commands copy their input
+and return `Future` values. Snapshot methods synchronously copy immutable state.
+Ordered queries and lifecycle operations also return `Future` values. Direct
+wake callbacks report queued events without participating in future completion.
+Read queued events with `RuntimeHandle.drainEvents()`. Narrow what a map or a
+runtime queues with `setEventMask`.
+
+Runtime, map, camera, and projection calls remain valid when Dart resumes an
+isolate on another native thread after `await`. Attach a render session directly
+from its map on the isolate that will own the graphics session.
 
 Resource-request completion is one-shot. Calling `complete()` or `close()`
 releases the provider reference even when completion reports a native error.

bindings/dart/lib/maplibre_native_ffi.dart

@@ -19,6 +19,6 @@ export 'src/runtime/runtime.dart'
         CustomMvtVectorCallbackLifecycleProbe,
         customMvtVectorCallbackProbeForTesting,
         decodeRuntimeEventBatchForTesting,
-        mapAttachRefIdForTesting,
+        mapHandleIdForTesting,
         runtimeHandleIdForTesting;
 export 'src/style/style.dart';

bindings/dart/lib/src/camera/camera.dart

@@ -6,6 +6,23 @@ import '../geo/geo.dart';
 export '../geo/geo.dart'
     show EdgeInsets, LatLng, LatLngBounds, Quaternion, ScreenPoint, Vec3;
 
+/// Native execution mode for one atomic camera update.
+enum CameraUpdateMode {
+  /// Applies the camera immediately.
+  jump(0),
+
+  /// Animates with easing.
+  ease(1),
+
+  /// Animates along a flight path.
+  fly(2);
+
+  const CameraUpdateMode(this.rawValue);
+
+  /// Native camera update mode value.
+  final int rawValue;
+}
+
 /// Cubic easing curve for animated camera transitions.
 final class UnitBezier {
   /// Creates a cubic unit bezier.
@@ -148,6 +165,49 @@ final class AnimationOptions {
       Object.hash(durationMs, velocity, minZoom, easing, transitionId);
 }
 
+/// Relative camera operation kind.
+enum CameraDeltaKind {
+  move(0),
+  scale(1),
+  bearing(2),
+  pitch(3);
+
+  const CameraDeltaKind(this.rawValue);
+
+  /// Native camera delta kind value.
+  final int rawValue;
+}
+
+/// One relative camera operation.
+final class CameraDelta {
+  /// Creates a relative camera operation.
+  const CameraDelta({
+    this.kind = CameraDeltaKind.move,
+    this.offset = const ScreenPoint(0, 0),
+    this.amount = 0,
+    this.anchor,
+    this.animation = const AnimationOptions(),
+  });
+
+  final CameraDeltaKind kind;
+  final ScreenPoint offset;
+  final double amount;
+  final ScreenPoint? anchor;
+  final AnimationOptions animation;
+
+  @override
+  bool operator ==(Object other) =>
+      other is CameraDelta &&
+      other.kind == kind &&
+      other.offset == offset &&
+      other.amount == amount &&
+      other.anchor == anchor &&
+      other.animation == animation;
+
+  @override
+  int get hashCode => Object.hash(kind, offset, amount, anchor, animation);
+}
+
 /// Optional fitting controls for camera-for-viewport queries.
 final class CameraFitOptions {
   /// Creates camera fit options.

bindings/dart/lib/src/error/maplibre_exception.dart

@@ -20,6 +20,21 @@ final class MaplibreStatus {
   /// A native MapLibre error or C++ exception was converted to status.
   static const nativeError = MaplibreStatus._('nativeError', -5);
 
+  /// The operation completed after cancellation was requested.
+  static const cancelled = MaplibreStatus._('cancelled', -6);
+
+  /// The call raced a driver call in flight; retry once it returns.
+  static const busy = MaplibreStatus._('busy', -7);
+
+  /// The render target was lost and the session cannot continue with it.
+  static const targetLost = MaplibreStatus._('targetLost', -8);
+
+  /// No result was ready yet; poll or wait for the wake and retry.
+  static const notReady = MaplibreStatus._('notReady', -9);
+
+  /// No object has the requested ID.
+  static const notFound = MaplibreStatus._('notFound', -10);
+
   /// An unknown status value returned by a newer or incompatible native build.
   static MaplibreStatus unknown(int nativeStatusCode) =>
       MaplibreStatus._('unknown', nativeStatusCode);
@@ -39,6 +54,11 @@ final class MaplibreStatus {
         -3 => wrongThread,
         -4 => unsupported,
         -5 => nativeError,
+        -6 => cancelled,
+        -7 => busy,
+        -8 => targetLost,
+        -9 => notReady,
+        -10 => notFound,
         _ => unknown(nativeStatusCode),
       };
 
@@ -79,6 +99,7 @@ abstract final class MaplibreException implements Exception {
       -3 => WrongThreadException(nativeStatusCode, diagnostic),
       -4 => UnsupportedFeatureException(nativeStatusCode, diagnostic),
       -5 => NativeErrorException(nativeStatusCode, diagnostic),
+      -10 => NotFoundException(nativeStatusCode, diagnostic),
       _ => UnknownMaplibreException(status, nativeStatusCode, diagnostic),
     };
   }
@@ -149,6 +170,13 @@ final class NativeErrorException extends MaplibreException {
     : super(MaplibreStatus.nativeError, nativeStatusCode, diagnostic);
 }
 
+/// Native not-found failure: no object has the requested ID.
+final class NotFoundException extends MaplibreException {
+  /// Creates a not-found exception.
+  const NotFoundException(int? nativeStatusCode, String diagnostic)
+    : super(MaplibreStatus.notFound, nativeStatusCode, diagnostic);
+}
+
 /// Loaded native library uses a different C ABI contract version.
 final class AbiVersionMismatchException extends MaplibreException {
   /// Creates an ABI-version mismatch exception.